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¶

pocvip [OPTION] COMMANDS

Options¶

Option	Description
`-h`, `--help`	Display this help message and exit.
`-x`	Disable the GUI (run in command-line mode).
`--verbosity <level>`	Set verbosity level. `<0` is silent. Default: `0`.
`--shoreline <path>`	Specify a default shoreline file path.
`--landmask <path>`	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 <path>.
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:

-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):

selec\ 
  tFile dataFiel\ 
    ds.nc

The following commands are ignored (invalid syntax):

# 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):

-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.
`--<var>`	Set the status of `<var>` 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¶

pocvip -f dataFields.nc

Open All NetCDF Files in a Directory¶

pocvip ./*.nc

Select a Variable and Display It¶

pocvip -f dataFields.nc -v temperature

Run a Script¶

pocvip . my_script.pocvip

Use a Custom Shoreline File¶

pocvip --shoreline /path/to/coastline.cst -f dataFields.nc

Disable GUI while opening a file, run a script on this file, then exit¶

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:

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¶

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).

Command-Line Mode (-x):

Disables the GUI and runs pocvip in a pure command-line mode.
Useful for scripting and batch processing.

Scripting:

Scripts (.pocvip files) can be executed using the . or runScript command.
Scripts can include multiple commands, one per line.

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.

History:

Command history is saved to ~/.pocvip_history on exit.

Crash Handling:

If pocvip crashes, a black box file (~/.pocvip_blackbox) is generated for debugging.
Include this file in bug reports.