CLI Reference

Complete command-line reference for PIVTools. All commands support the --active-paths flag for batch processing specific path sets.

Quick Reference

# Initialise & Process
pivtools-cli init
pivtools-cli instantaneous
pivtools-cli ensemble
# Camera Model Generation
pivtools-cli detect-planar
pivtools-cli detect-charuco
pivtools-cli detect-stereo-planar
pivtools-cli detect-stereo-charuco
# Post-Processing
pivtools-cli apply-calibration
pivtools-cli apply-stereo
pivtools-cli transform
pivtools-cli merge
pivtools-cli statistics
# Visualisation
pivtools-cli video

Common Workflows

Complete PIV Analysis

# 1. Initialise workspace
pivtools-cli init

# 2. Edit config.yaml with your settings

# 3. Generate camera calibration model
pivtools-cli detect-planar

# 4. Run PIV processing
pivtools-cli instantaneous

# 5. Apply calibration to vectors
pivtools-cli apply-calibration

# 6. Transform if needed
pivtools-cli transform -o flip_ud

# 7. Merge cameras (if multi-camera)
pivtools-cli merge

# 8. Compute statistics
pivtools-cli statistics

# 9. Create video
pivtools-cli video -v mag

Stereo PIV Workflow

# Generate stereo calibration model
pivtools-cli detect-stereo-charuco

# Run PIV processing for both cameras
pivtools-cli instantaneous

# Apply stereo 3D reconstruction (ux, uy, uz)
pivtools-cli apply-stereo --camera-pair 1,2

# Compute statistics on stereo data
pivtools-cli statistics --stereo

# Create video from stereo data
pivtools-cli video --data-source stereo -v uz

Batch Processing Multiple Experiments

# Process specific path sets only
pivtools-cli instantaneous -p 0,1,2

# Process single path
pivtools-cli instantaneous -p 0
pivtools-cli apply-calibration -p 0
pivtools-cli statistics -p 0

# Loop through experiments
for exp in exp1 exp2 exp3; do
    (cd /data/$exp && pivtools-cli instantaneous)
done

All Commands

Click any command to expand options and examples. All commands read settings from config.yaml in the current directory.

Transform Operations

Available operations for pivtools-cli transform -o:

flip_udFlip vertically (up-down)
flip_lrFlip horizontally (left-right)
rotate_90_cwRotate 90 degrees clockwise
rotate_90_ccwRotate 90 degrees counter-clockwise
rotate_180Rotate 180 degrees
swap_ux_uySwap velocity components
invert_ux_uyNegate ux and uy
scale_velocity:NScale velocities by factor N
scale_coords:NScale coordinates by factor N

Environment Variables

VariableDescription
PIV_ACTIVE_PATHSOverride active paths (comma-separated indices)
MALLOC_TRIM_THRESHOLD_Set to "0" for better memory management
OMP_NUM_THREADSControl OpenMP thread count
Example
# Override active paths via environment
PIV_ACTIVE_PATHS=0,1 pivtools-cli instantaneous

# Control threading
OMP_NUM_THREADS=4 pivtools-cli instantaneous

Getting Help

# Show all available commands
pivtools-cli --help

# Show help for specific command
pivtools-cli instantaneous --help
pivtools-cli video --help

Need More Detail?

Each command has detailed documentation in its respective section with full YAML configuration examples.