# pocvip v2.1.3 **Mercurial revision 1895:1c1aec60d28e | 2026-07-04** --- ## Description `pocvip` (**POC Viewer and Processing**) is a **general-purpose viewer** for geo-referenced datasets. ### Strengths and philosophy - Plot geo-referenced observations and simulations (PROJ/GDAL library) - Compare fields no matter the format or grid - Basic operations - True interpolation in regard of the grid and node conventions - Interactive and script usage - Efficient usage of multi-cpu for both laptop and clusters --- ## Usage ```bash pocvip [OPTION] COMMANDS ``` --- ## Options | Option | Description | | --------------------- | -------------------------------------------------- | | `-h`, `--help` | Display this help message and exit. | | `-x` | Disable the GUI (run in command-line mode). | | `--verbosity ` | Set verbosity level. `<0` is silent. Default: `0`. | | `--shoreline ` | Specify a default shoreline file path. | | `--landmask ` | Specify a default landmask file path. | --- ## Commands ### **General Rules** - A command line may start with **any number of spaces**. - Commands are **case-insensitive** (e.g., `selectFile`, `SELECTFILE`, or `SeLeCtFiLe` are equivalent). - Paths ending with `/` or starting with `./`, `../`, or `/` are automatically treated as `selectFile `. - **Aliases** are case-sensitive (e.g., `-f` is an alias for `selectFile`, but `-F` is not). - If a command is not recognized, the line is **ignored**. - Arguments are passed as everything after the command name (including spaces). - Lines ending with `\` are concatenated with the next line (excluding the `\`). > **⚠️ Warning:** It is **impossible** to open files with paths containing carriage returns (`\n`). ### **Command Syntax Examples** All the following are equivalent and open the file `dataFields.nc`: ```bash -f dataFields.nc -f dataFields.nc selectFile dataFields.nc SELECTFILE dataFields.nc sEleCTfilE dataFields.nc ``` The following 3 lines form a single command (equivalent to the above): ```bash selec\ tFile dataFiel\ ds.nc ``` The following commands are **ignored** (invalid syntax): ```bash # selectFile dataFields.nc # `#` is not a valid command ,selectFile dataFields.nc # `,selectFile` is not a valid command ``` The following commands **fail** (due to extra spaces): ```bash -f dataFields.nc # Trailing space: `dataFields.nc ` does not exist -f dataFields.nc # Leading space: ` dataFields.nc` does not exist ``` --- ### **Command List** | Command (Aliases) | Description | | ------------------- | ------------------------------------------------------------------- | | `?`, `help` | Display help about commands. | | `-f`, `selectFile` | Open or select a file. | | `-v`, `selectVar` | Select a variable. | | `-a`, `atted` | Set or delete an attribute. | | `-s`, `setStatus` | Show/set the status of the selected variable or file. | | `-e`, `edit` | Edit a notebook or polygon. | | `setView_reworked` | Set the view location in time/space, refresh, or compute a formula. | | `-w`, `selectView` | Create or select a view. | | `-n`, `renameView` | Rename the currently selected view. | | `-p`, `saveView` | Save the image displayed by the view or extract time series. | | `-r`, `resizeView` | Resize the selected view. | | `-q`, `exit` | Exit `pocvip` (saves history to `~/.pocvip_history`). | | `!`, `system` | Execute a shell command (equivalent to the C function `system`). | | `cd`, `chdir` | Change directory (equivalent to the C function `chdir`). | | `rm`, `unlink` | Remove a file (equivalent to the C function `unlink`). | | `.`, `runScript` | Run a script. | | `atted_reworked` | Set or delete an attribute (reworked version). | | `closeView` | Close the currently selected view. | | `duplicateView` | Duplicate the current view. | | `intersect` | Intersect with a coastline or interpolate an edited notebook. | | `printView` | Save the image displayed by the view or extract time series. | | `prompt` | Prompt the user for the value of a script variable. | | `renameFile` | Rename the selected file. | | `selectFile_legacy` | Open or select a file (legacy version). | | `set` | Set the value of a script variable. | | `--` | Set the status of `` in `settings/` or `drawings/`. | > **Note:** > > - Use `--brief` as an argument to display a command's one-line help. > - Use `-h` or `--help` as an argument to display a command's long help. --- ## Examples ### **Open a File** ```bash pocvip -f dataFields.nc ``` ### **Open All NetCDF Files in a Directory** ```bash pocvip ./*.nc ``` ### **Select a Variable and Display It** ```bash pocvip -f dataFields.nc -v temperature ``` ### **Run a Script** ```bash pocvip . my_script.pocvip ``` ### **Use a Custom Shoreline File** ```bash pocvip --shoreline /path/to/coastline.cst -f dataFields.nc ``` ### **Disable GUI while opening a file, run a script on this file, then exit** ```bash pocvip -x -f dataFields.nc -v ssh . my_script.pocvip -q ``` --- ## Environment Variables `pocvip` uses **OpenMP** (version 201511) for parallel processing. The following environment variables are supported: | Variable | Description | | ----------------- | ----------------------------------------- | | `OMP_NUM_THREADS` | Number of threads to use. | | `OMP_SCHEDULE` | Runtime schedule type and chunk size. | | `OMP_DYNAMIC` | Enable/disable dynamic thread adjustment. | | `OMP_NESTED` | Enable/disable nested parallelism. | **Example:** ```bash OMP_NUM_THREADS=4 pocvip -f dataFields.nc ``` > **⚠️ Warning:** If running on a machine with high CPU load, limit the number of threads to the number of **free CPUs** to avoid performance issues. --- ## Notes 1. **File Paths:** - Paths are resolved relative to the current working directory. - Use absolute paths (e.g., `/path/to/file.nc`) or relative paths (e.g., `./file.nc`, `../data/file.nc`). 2. **Command-Line Mode (`-x`):** - Disables the GUI and runs `pocvip` in a **pure command-line mode**. - Useful for scripting and batch processing. 3. **Scripting:** - Scripts (`.pocvip` files) can be executed using the `.` or `runScript` command. - Scripts can include multiple commands, one per line. 4. **Default Files:** - `pocvip` loads default settings from: - `settings/` directory (for configuration). - `drawings/` directory (for polygons and annotations). - Default shoreline: `datadir/coasts.cst`. - Default landmask: `datadir/sirocco-landmask-osm-2026-quadtree.nc`. 5. **History:** - Command history is saved to `~/.pocvip_history` on exit. 6. **Crash Handling:** - If `pocvip` crashes, a black box file (`~/.pocvip_blackbox`) is generated for debugging. - Include this file in bug reports. --- ## See Also - [OpenMP Documentation](https://www.openmp.org/) (for parallel processing) - [NetCDF CF Conventions](http://cfconventions.org/) (for time coordinate standards) - [GTK Documentation](https://docs.gtk.org/) (for GUI-related features)