Skip to content

Parameter Reference

Complete reference for all sample and calibrate parameters.

Table of Contents

Required Parameters

--root-dir <path>

Description: Root directory containing video subdirectories.

Example: 

--root-dir /mnt/storage/AUV_data

Expected structure: 

/mnt/storage/AUV_data/
  Triton43_20250904T120000Z_Cam1_001.mp4
  Triton43_20250904T120500Z_Cam1_002.mp4
  Triton43_20250904T121000Z_Cam1_003.mp4

Requirements: - Must exist and be readable - Must contain .mp4 files with format: {vehicle}_{timestamp}_Cam{N}_{id}.mp4

Notes: - No default value (must be specified) - Use absolute paths to avoid ambiguity

--camera <id>

Description: Camera ID to process (matches Cam<N> in video filename).

Example: 

--camera 1

Effect: Processes only video files containing Cam1 in their filename (e.g., Triton43_20250904T120000Z_Cam1_001.mp4).

Default: (required, no default)

Multiple cameras: Run sample separately for each camera.

Quality Thresholds

--min-brightness <value>

Description: Minimum mean pixel value (0–255) for quality gate.

Range: 0.0–255.0

Default: 12.0

Typical values: - 5–10: Very dark environments (deep ocean at night) - 15–30: Dark environments (deep water with artificial lighting) - 30–60: Moderate (mid-water, ambient light) - 60+: Bright (shallow water, strong sunlight)

Effect: Rejects frames darker than threshold (sensor failure, occlusion, underexposure).

Tuning: Use calibrate to find p5 or p10 (rejects ~10–20% of darkest frames).

--max-brightness <value>

Description: Maximum mean pixel value (0–255) for quality gate.

Range: 0.0–255.0

Default: 243.0

Typical values: - 200–220: Strict (reject overexposed frames) - 220–240: Moderate (typical) - 240–255: Permissive (rarely reject)

Effect: Rejects frames brighter than threshold (overexposure, lighting artifacts).

Tuning: Use calibrate to find p90 or p95 (rejects ~5–10% of brightest frames).

--min-sharpness <value>

Description: Minimum Laplacian variance for quality gate.

Range: 0.0+

Default: 15.0

Typical values: - 5–10: Very permissive (accept significant blur) - 10–20: Permissive (typical for underwater imaging) - 20–40: Moderate (balanced) - 40–80: Strict (demand sharp focus) - 80+: Very strict (maximum quality)

Effect: Rejects blurry frames (motion blur, defocus, turbidity).

Tuning: Use calibrate to find p10–p25 depending on desired pass rate.

Notes: - Most sensitive to motion blur and focus quality - Typical rejection rate: 10–30%

--min-entropy <value>

Description: Minimum Shannon entropy (bits) for quality gate.

Range: 0.0–8.0

Default: 2.5

Typical values: - 1.5–2.0: Very permissive (accept near-uniform frames) - 2.0–2.5: Permissive (typical) - 2.5–3.5: Moderate (balanced) - 3.5–4.5: Strict (demand texture) - 4.5+: Very strict (dense detail only)

Effect: Rejects featureless frames (blue water, uniform backgrounds).

Tuning: Use calibrate to find p10–p25 depending on environment.

Notes: - Highly environment-dependent (open ocean vs. reef) - Typical rejection rate: 15–35%

Diversity Parameters

--max-frames <count>

Description: Maximum total frames to extract across all videos.

Range: 1+ (integer)

Default: 5000

Typical values: - 500–1000: Small dataset (quick annotation) - 1000–5000: Medium dataset (balanced) - 5000–20000: Large dataset (comprehensive) - 20000+: Very large (may need distributed annotation)

Effect: Budget for frame extraction. If quality filtering + diversity selection yields more frames, top max-frames by interest score are kept.

Tuning: Based on annotation capacity and dataset needs.

--n-bins <count>

Description: Number of bins per axis in diversity grid.

Range: 3–20 (integer, practical 5–12)

Default: 8

Total cells: n-bins³ (e.g., 8³ = 512)

Typical values: - 5–6: Coarse (125–216 cells, ~5–10% occupancy for small datasets) - 7–8: Balanced (343–512 cells, typical) - 9–10: Fine (729–1000 cells, large datasets) - 11–12: Very fine (1331–1728 cells, very large datasets)

Effect: - Higher: Finer feature distinctions, more diversity, sparser cells - Lower: Coarser grouping, less diversity, denser cells

Tuning: - Rule of thumb: \(\text{n\_bins} \approx \sqrt[3]{\frac{\text{num\_candidates}}{20}}\) - Check occupancy: After running, inspect output (target: 30–70% occupied cells)

--max-per-cell <count>

Description: Maximum frames extracted per grid cell.

Range: 1+ (integer)

Default: Auto-computed: \(\lceil \frac{\text{max\_frames}}{\text{n\_bins}^3} \rceil\)

Typical values: - 1–5: Force uniform diversity (limit dense cells) - 10–20: Balanced (default behavior) - 50+: Interest-driven (allow dense cells to dominate)

Effect: - Lower: More uniform representation (each cell contributes equally) - Higher: More interest-weighted (high-interest cells contribute more)

Tuning: - Leave as default unless you need strict uniform diversity or want to emphasize high-interest regions

Temporal Parameters

--min-gap <seconds>

Description: Minimum time gap (seconds) between frames from same video.

Range: 0.0+ (float)

Default: 1.0

Typical values: - 0.5–1.0: Fast-moving vehicle (>1 m/s) - 1.0–3.0: Moderate speed (0.5–1 m/s, typical AUVs) - 3.0–5.0: Slow-moving vehicle (<0.5 m/s) - 5.0–10.0: Static or near-static (benthic landers, stationary surveys)

Effect: Enforces temporal separation, prevents near-duplicate frames from same clip.

Tuning: - Estimate: \(\text{min\_gap} \approx \frac{\text{field\_of\_view}}{\text{vehicle\_speed}}\) - Example: 1m FOV, 0.5 m/s → 2 seconds

--sample-fps <rate>

Description: Frame sampling rate (frames per second) for metric computation.

Range: 0.1–30.0 (float, practical 0.5–5.0)

Default: 1.0

Typical values: - 0.5: Sparse (every 2 seconds, fast preview) - 1.0: Moderate (every 1 second, typical) - 2.0: Dense (every 0.5 seconds, catch short events) - 5.0+: Very dense (rarely needed, slow)

Effect: - Higher: More frames examined, longer runtime, more candidates - Lower: Fewer frames examined, faster runtime, fewer candidates (may miss short events)

Tuning: - Start with 1.0 fps (60x speedup for 60 fps video) - Increase if missing important events - Decrease for faster preview runs

Notes: - Original video frame rate is irrelevant (sampling rate is independent) - 1 fps is sufficient for most AUV surveys (slow-changing scenes)

Input/Output Parameters

--output-dir <path>

Description: Directory for extracted frame images.

Default: ./sampled_frames

Example: 

--output-dir /mnt/results/Triton43_frames

Behavior: - Created if doesn't exist - Frames are saved as PNG (lossless) with ISO timestamp filenames

Naming convention: 

Triton43_Cam1_20250904T120315Z_0001234.png

Format: {vehicle}_Cam{N}_{ISO_timestamp}_{frame_idx:07d}{ext}

--cache-dir <path>

Description: Directory for metric cache files (JSON).

Default: ./.metric_cache

Example: 

--cache-dir /tmp/triton_cache

Behavior: - Cache files are named by FNV-1a hash of video path and parameters - Reused across runs with same video and parameters - Safe to delete (will be regenerated)

Performance: 10–100x speedup on repeated runs (metric computation dominates runtime).

Tuning: Use fast local storage (SSD) for best cache performance.

--format <format>

Description: Output image format.

Values: .png | .jpg | .jpeg

Default: .png

Comparison:

Format Size Quality Speed
PNG Large (lossless) Perfect Slower
JPEG Small (lossy) High (q=95) Faster

Use PNG for: - Archival datasets - Downstream processing requiring lossless data

Use JPEG for: - Quick visual inspection - Storage-constrained environments - Web display

Performance Parameters

--jobs <count>

Description: Number of parallel threads for metric computation.

Range: 1–num_cores (integer)

Default: 1 (single-threaded)

Example: 

--jobs 4  # Use 4 CPU cores

Effect: Parallelizes metric extraction via OpenMP.

Speedup: ~linear up to 4–8 cores (I/O bound beyond that).

Tuning: - Use --jobs $(nproc) for maximum speed - Reduce if system is under load - No benefit beyond ~8 cores (disk I/O bottleneck)

Notes: - Only parallelizes metric computation (Pass 1) - Diversity selection (Pass 2) and extraction (Pass 3) are serial

Advanced Parameters

--examine-every <N>

Description: Examine every Nth frame (alternative to --sample-fps).

Range: 1+ (integer)

Default: Computed from --sample-fps and video FPS

Example: 

--examine-every 30  # Examine every 30th frame (1 fps at 30 fps video)

Relationship to sample-fps: \(\(\text{examine\_every} = \frac{\text{video\_fps}}{\text{sample\_fps}}\)\)

Use case: Direct control when you know frame skip rate.

Notes: Prefer --sample-fps for clarity (independent of video frame rate).

--verbose

Description: Enable detailed logging (progress, diagnostics).

Default: Off (brief output only)

Example: 

./sample --root-dir /data --camera 1 --verbose

Output includes: - Per-video progress (frames examined, metrics computed, cache hits) - Intermediate counts (quality pass, temporal filter, grid selection) - Timing information

Use case: Debugging, understanding processing pipeline.

Parameter Precedence

When the same parameter can be specified multiple ways:

  1. Command-line flag (highest priority)
  2. Environment variable (if supported)
  3. Config file (not currently supported)
  4. Default value (lowest priority)

Parameter Validation

The tool validates parameters at startup:

  • root-dir: Must exist and contain .mp4 video files
  • camera: Must be positive integer
  • min/max-brightness: Must be in [0, 255], min < max
  • min-sharpness: Must be non-negative
  • min-entropy: Must be in [0, 8]
  • max-frames: Must be positive
  • n-bins: Must be ≥ 3 (practical limit: 3–20)
  • min-gap: Must be non-negative
  • sample-fps: Must be positive
  • jobs: Must be ≥ 1

Errors halt execution (no partial runs with invalid parameters).

Common Parameter Combinations

High-Quality Small Dataset

./sample \
  --root-dir /data \
  --camera 1 \
  --min-brightness 40 \
  --min-sharpness 50 \
  --min-entropy 3.0 \
  --max-frames 500 \
  --min-gap 2.0 \
  --jobs 4

Effect: Strict quality, small budget, strong temporal separation.

Balanced Medium Dataset

./sample \
  --root-dir /data \
  --camera 1 \
  --min-brightness 20 \
  --min-sharpness 20 \
  --min-entropy 2.5 \
  --max-frames 5000 \
  --min-gap 1.0 \
  --jobs 4

Effect: Moderate quality, typical budget, typical settings. (Recommended default)

Permissive Large Dataset

./sample \
  --root-dir /data \
  --camera 1 \
  --min-brightness 10 \
  --min-sharpness 10 \
  --min-entropy 2.0 \
  --max-frames 20000 \
  --min-gap 0.5 \
  --n-bins 10 \
  --jobs 8

Effect: Permissive quality, large budget, fine diversity grid, many cores.

Parameter Tuning Checklist

Before running sample, ensure:

  • [ ] --root-dir points to directory containing video files
  • [ ] --camera matches Cam<N> in your video filenames
  • [ ] Quality thresholds tuned via calibrate (target 40–70% pass rate)
  • [ ] --max-frames matches annotation capacity
  • [ ] --min-gap appropriate for vehicle speed
  • [ ] --sample-fps high enough to catch events (1–2 fps typical)
  • [ ] --n-bins appropriate for candidate count (7–9 typical)
  • [ ] --jobs set to utilize available cores (4–8 typical)

Next Steps