Skip to content

Troubleshooting

Common issues and their solutions.

Build Issues

CMake can't find OpenCV

Error: 

CMake Error at CMakeLists.txt:X (find_package):
  Could not find a package configuration file provided by "OpenCV"

Solutions:

  1. Verify OpenCV is installed: 

    pkg-config --modversion opencv4

  2. If not installed, install from system packages: 

    # Ubuntu/Debian
sudo apt install libopencv-dev

# Fedora
sudo dnf install opencv-devel

# macOS
brew install opencv

  3. If installed but not found, specify path: 

    cmake -DOpenCV_DIR=/usr/local/lib/cmake/opencv4 ..

Common paths: - Ubuntu: /usr/lib/x86_64-linux-gnu/cmake/opencv4 - macOS (Homebrew): /opt/homebrew/Cellar/opencv/4.x.y/lib/cmake/opencv4

Compiler doesn't support C++17

Error: 

error: 'filesystem' is not a namespace-name
error: 'optional' is not a member of 'std'

Solutions:

  1. Check compiler version: 

    g++ --version  # Need GCC 7+
clang++ --version  # Need Clang 5+

  2. Update compiler: 

    # Ubuntu
sudo apt install g++-9

# macOS (Xcode Command Line Tools)
xcode-select --install

  3. Specify compiler explicitly: 

    cmake -DCMAKE_CXX_COMPILER=g++-9 ..

OpenMP not found

Warning (non-fatal): 

Could NOT find OpenMP_CXX

Impact: --jobs parallelism disabled (slower Pass 1).

Solutions:

  1. Install OpenMP: 

    # Ubuntu
sudo apt install libomp-dev

# macOS
brew install libomp

  2. Rebuild: 

    cd build && rm CMakeCache.txt && cmake .. && make

  3. Verify: 

    ./sample --help | grep jobs  # Should list --jobs option

Runtime Issues

Videos not opening

Error: 

[error] cannot reopen video.mp4

Causes:

  1. OpenCV built without FFMPEG/GStreamer support
  2. Codec not supported (e.g., H.265/HEVC)
  3. File corrupted or incomplete

Solutions:

  1. Check FFMPEG support: 
    pkg-config --libs opencv4 | grep -i ffmpeg

If empty, OpenCV doesn't have FFMPEG. Reinstall: 

# Remove pip version (doesn't include video codecs)
pip3 uninstall opencv-python opencv-python-headless

# Install system package
sudo apt install libopencv-dev

  1. Test video file: 

    ffmpeg -i video.mp4  # Check codec info
ffplay video.mp4     # Test playback

  2. Convert to compatible codec (H.264): 

    ffmpeg -i input.mp4 -c:v libx264 -c:a aac output.mp4

No frames selected

Output: 

Final selection: 0 frames
No frames selected — try --max-frames or --min-gap.

Causes:

  1. Quality gates too strict: All frames rejected
  2. Temporal filter too aggressive: --min-gap too large for short videos
  3. No videos found: Wrong --root-dir or --camera

Solutions:

  1. Run calibrate to see pass rate: 
    ./calibrate /path/to/video.mp4

If pass rate < 10%, relax thresholds: 

./sample \
  --min-brightness 10 \
  --min-sharpness 10 \
  --min-entropy 2.0 \
  ...

  1. Reduce temporal gap: 

    ./sample --min-gap 0.5 ...  # Allow frames 0.5s apart

  2. Verify videos found: 

    find /path/to/root-dir -name "*Cam1*.mp4"

Cache not working

Symptom: Pass 1 always recomputes metrics (no "cache hit" messages).

Causes:

  1. --no-cache flag passed
  2. Video file modified (timestamp or size changed)
  3. Different --sample-fps than cached run
  4. Cache directory not writable

Solutions:

  1. Check cache directory: 

    ls -la .metric_cache/

  2. Check permissions: 

    chmod 755 .metric_cache/

  3. Verify cache format (should be JSON): 

    cat .metric_cache/<hash>.json | jq .

  4. Force cache rebuild: 

    rm -rf .metric_cache/
./sample ...  # Rebuilds cache

Quality Issues

Too many dark frames

Symptom: Output contains frames darker than expected.

Solutions:

  1. Raise min-brightness: 

    ./sample --min-brightness 30 ...  # Reject darker frames

  2. Check calibrate output: 

    ./calibrate video.mp4

Look at brightness distribution. If median is low (< 50), your videos are naturally dark — may need to accept darker frames or improve lighting.

Too many blurry frames

Symptom: Output contains out-of-focus or motion-blurred frames.

Solutions:

  1. Raise min-sharpness: 

    ./sample --min-sharpness 40 ...  # Reject blurrier frames

  2. Check if blur is pervasive: 

    ./calibrate video.mp4

If sharpness p95 < 50, most frames are blurry (vehicle motion, turbidity, poor optics). Consider: - Slower vehicle speed - Better image stabilization - Accept some blur as unavoidable

Too many featureless frames (blue water)

Symptom: Output dominated by uniform blue/green water.

Solutions:

  1. Raise min-entropy: 

    ./sample --min-entropy 3.5 ...  # Reject low-texture frames

  2. Lower max-per-cell (limit contribution from common scenes): 

    ./sample --max-per-cell 5 ...

  3. Increase n-bins (fragment common cells): 

    ./sample --n-bins 10 ...

Missing rare events

Symptom: Known interesting frames (organisms, features) not selected.

Causes:

  1. Quality gates reject them: Too strict thresholds
  2. Temporal filter rejects them: Too large --min-gap
  3. Not examined: Too low --sample-fps misses short events
  4. Out-competed: Rare cells have lower interest scores than common cells

Solutions:

  1. Relax quality gates: 

    ./sample --min-sharpness 15 --min-entropy 2.5 ...

  2. Reduce temporal gap: 

    ./sample --min-gap 1.0 ...

  3. Increase sample rate: 

    ./sample --sample-fps 2.0 ...  # Examine twice as many frames

  4. Lower max-per-cell (give rare cells more budget): 

    ./sample --max-per-cell 5 ...

Diversity Issues

Near-duplicate frames

Symptom: Multiple output frames from same video look nearly identical.

Solutions:

  1. Increase min-gap: 

    ./sample --min-gap 3.0 ...  # Enforce 3-second separation

  2. Increase n-bins (separate similar frames into different cells): 

    ./sample --n-bins 10 ...

Over-sampling common scenes

Symptom: One type of scene (e.g., blue water) dominates output.

Solutions:

  1. Lower max-per-cell: 

    ./sample --max-per-cell 5 ...  # Limit each cell to 5 frames

  2. Raise quality thresholds (reject common low-quality frames): 

    ./sample --min-entropy 3.5 ...

  3. Two-pass sampling: First pass for general diversity, second pass targeting rare conditions (see Tuning Guide)

Under-utilizing frame budget

Symptom: Output has far fewer frames than --max-frames.

Causes:

  1. Insufficient candidates after quality filtering
  2. Temporal filter too aggressive
  3. Grid too sparse (too many empty cells)

Solutions:

  1. Relax quality gates: 

    ./sample --min-brightness 15 --min-sharpness 15 --min-entropy 2.0 ...

  2. Reduce min-gap: 

    ./sample --min-gap 0.5 ...

  3. Lower n-bins (denser cells): 

    ./sample --n-bins 6 ...

  4. Add more source videos

Performance Issues

Slow Pass 1 (metric extraction)

Symptom: Pass 1 takes minutes to hours.

Solutions:

  1. Enable parallelism: 
    ./sample --jobs 8 ...  # Use 8 threads (4–8× speedup)

Verify OpenMP is enabled: 

ldd ./sample | grep omp

  1. Use cache: Second run should be ~10× faster (cache hits).

  2. Reduce sample rate: 

    ./sample --sample-fps 0.5 ...  # Examine half as many frames

  3. Use SSD storage (not spinning disk): Video I/O is bottleneck.

Slow Pass 3 (frame extraction)

Symptom: Pass 3 takes long despite few frames.

Cause: Random seeks across videos (each seek ~10–50 ms).

Solutions:

  1. Use SSD storage (faster seeks)

  2. Pre-sort videos (groups by video are sorted internally, but if selecting from many videos, seeks are unavoidable)

  3. Use JPEG (faster encoding): 

    ./sample --format .jpg ...

High memory usage

Symptom: Process uses >1 GB RAM.

Causes: Very large candidate pool (hundreds of thousands of frames).

Solutions:

  1. Reduce sample rate: 

    ./sample --sample-fps 0.5 ...

  2. Process videos in batches: 

    ./sample --root-dir /data/batch1 ...
./sample --root-dir /data/batch2 ...

  3. Not typically an issue: Tool uses ~50 MB per 100K frames (< 500 MB typical).

Unexpected Behavior

Different results on repeated runs

Expected: Results should be deterministic (same every time).

If not:

  1. Check filesystem timestamps (cache key includes last_modified_time): 

    stat video.mp4 | grep Modify

  2. Disable cache: 

    ./sample --no-cache ...

If results now deterministic, cache was corrupted. Delete and rebuild: 

rm -rf .metric_cache/
./sample ...

Filenames not as expected

Expected format: 

<vehicle>_Cam<N>_<ISO_timestamp>_<frame_idx>.png

If incorrect:

  1. Check source video filename: Must match pattern *Triton*Cam* or similar.

  2. Verify metadata extraction (in code): triton_sampling.cpp parses filename for vehicle and camera.

  3. If using custom naming: Modify parse_metadata() in triton_sampling.cpp to match your convention.

Getting Help

If issues persist:

  1. Check version: 

    git log -1 --oneline

  2. Gather diagnostics: 

    # System info
uname -a
g++ --version
pkg-config --modversion opencv4

# Test video
ffmpeg -i problem_video.mp4

# Test execution
./sample --help
./calibrate --help

  3. Open GitHub issue with:

  4. Command you ran
  5. Full error output
  6. calibrate output on problem video
  7. System info (OS, OpenCV version, compiler)

Known Limitations

Codec Support

Limitation: Depends on OpenCV's FFMPEG/GStreamer backend. Some codecs (e.g., H.265/HEVC, AV1) may not be supported.

Workaround: Convert to H.264/AVC: 

ffmpeg -i input.mp4 -c:v libx264 -c:a aac output.mp4

Large Video Files (>50 GB)

Limitation: Seek operations may be slow on very large files.

Workaround: Split into smaller chunks: 

ffmpeg -i large.mp4 -c copy -f segment -segment_time 600 chunk_%03d.mp4

Non-Monotonic Timestamps

Limitation: If video timestamps are non-sequential (editing artifacts), frame ordering may be incorrect.

Workaround: Re-encode with correct timestamps: 

ffmpeg -i input.mp4 -c:v copy -c:a copy -avoid_negative_ts make_zero output.mp4

Next Steps

  • Tuning Guide: Optimize parameters for your data
  • Usage: Complete command-line reference
  • Algorithm: Understand the sampling pipeline