CLI Reference
Complete command-line reference for pivtools-cli. All commands read from config.yaml in the current directory.
Quick Reference
Both apply commands need to be told which directories to work on. apply-calibration and apply-stereo exit with an error unless you pass either --all-paths, which derives every base path from the config the way the GUI does, or an explicit input and output directory pair. There is no default, so a bare invocation will not run.
# Init and Process
pivtools-cli init
pivtools-cli instantaneous
pivtools-cli ensemble
# Calibration
pivtools-cli init-settings
pivtools-cli detect-charuco
pivtools-cli detect-stereo
pivtools-cli detect-joint
pivtools-cli scale-factor
# Post-Processing
pivtools-cli apply-calibration
pivtools-cli apply-stereo
pivtools-cli self-calibrate
pivtools-cli global-frame
pivtools-cli transform
pivtools-cli merge
pivtools-cli statistics
# Visualisation
pivtools-cli video
Common Workflows
2D PIV (Single or Multi-Camera)
pivtools-cli init # Create config.yaml # Edit config.yaml with your settings pivtools-cli detect-charuco # Generate camera model (ChArUco; dotboard/stepped via GUI) pivtools-cli instantaneous # Run PIV pivtools-cli apply-calibration --board charuco --all-paths # Pixels to m/s pivtools-cli transform -o flip_ud # Geometric transform (optional) pivtools-cli merge # Merge cameras (if multi-camera) pivtools-cli statistics # Mean, TKE, vorticity, etc. pivtools-cli video -v mag # Create video
Stereo PIV
pivtools-cli detect-stereo # Stereo camera model (ChArUco) pivtools-cli instantaneous # PIV for both cameras pivtools-cli self-calibrate --board charuco --camera-pair 1,2 # Correct laser-sheet misalignment (optional) pivtools-cli apply-stereo --board charuco --camera-pair 1,2 --all-paths # 3D reconstruction (ux, uy, uz) pivtools-cli statistics --source-endpoint stereo pivtools-cli video --data-source stereo -v uz
Stepped Board Stereo PIV
# Stepped-board detection is GUI-only: it needs interactive # fiducial and level picking, so there is no headless equivalent. # Calibrate on the Stereo Stepped tab, then continue from the CLI: pivtools-cli instantaneous # PIV for both cameras pivtools-cli apply-stereo --board stepped --all-paths # 3D reconstruction pivtools-cli statistics --source-endpoint stereo
Batch Processing
# PIV + post-processing accept --active-paths / -p pivtools-cli instantaneous -p 0,1,2 pivtools-cli statistics -p 0,1,2 # Calibration applies across all configured paths pivtools-cli apply-calibration --board charuco --all-paths
All Commands
Click any command to expand options and examples. PIV and post-processing commands support --active-paths / -p for batch path selection; calibration commands instead use --source / --all-paths.
Transform Operations
Available for pivtools-cli transform -o. Comma-separate multiple operations.
| Operation | Description |
|---|---|
| flip_ud | Flip vertically (up-down) |
| flip_lr | Flip horizontally (left-right) |
| rotate_90_cw | Rotate 90 degrees clockwise |
| rotate_90_ccw | Rotate 90 degrees counter-clockwise |
| rotate_180 | Rotate 180 degrees |
| swap_ux_uy | Swap velocity components |
| invert_ux | Negate ux only (also negates UV stress) |
| invert_uy | Negate uy only (also negates UV stress) |
| invert_ux_uy | Negate ux and uy |
| scale_velocity:N | Scale velocities by factor N |
| scale_coords:N | Scale coordinates by factor N |
Environment Variables
| Variable | Description |
|---|---|
| PIV_ACTIVE_PATHS | Override active paths (comma-separated indices) |
| MALLOC_TRIM_THRESHOLD_ | Set to "0" automatically by the PIV pipelines (glibc memory trimming on Linux) |
| OMP_NUM_THREADS | Ignored by the instantaneous and ensemble pipelines, which overwrite it at import from processing.omp_threads. Set that config key instead. Still honoured by tools that do not go through those pipelines. |
| PIV_CAMERA | Restrict a run to one camera. Set by the --camera flag. Process-global, so it must never be set in the long-lived GUI server process, where every later request would silently flip to single-camera mode. |
Example
PIV_ACTIVE_PATHS=0,1 pivtools-cli instantaneous # To set the thread count, use the config key rather than the env var: # processing: # omp_threads: 4
Getting Help
pivtools-cli --help # All commands pivtools-cli instantaneous --help # Command-specific help pivtools-cli video --help
Need More Detail?
Each command has detailed documentation in its respective manual section.