Skip to content

Common Scenarios

Domain-specific parameter examples and calibration strategies.

Scenario Index

  1. Deep-Sea Benthic Survey (>200m)
  2. Mid-Water Plankton/Particle Imaging
  3. Shallow Reef Survey (<50m)
  4. Fast Transect (High Vehicle Speed)
  5. Static Benthic Lander
  6. Low-Quality Optics (Blurry/Turbid)
  7. High-Quality Dataset (Archival)
  8. Quick Preview (Speed-Priority)

Deep-Sea Benthic Survey (>200m)

Environment Characteristics

  • Low ambient light (dark, artificial lighting only)
  • Static scenes (slow-moving or stationary organisms)
  • High-detail features (organisms, geology, debris)
  • Slow vehicle speed (0.2–0.8 m/s)
  • Stable camera (minimal motion blur)

Typical Metric Distributions

brightness:  min=8   p5=15   median=40   p95=120  max=180
sharpness:   min=10  p5=20   median=35   p95=90   max=150
entropy:     min=2.0 p5=2.8  median=3.8  p95=5.2  max=6.0
motion:      min=0.5 p5=2.0  median=6.0  p95=18   max=45

./sample \
  --root-dir /data/benthic_survey \
  --camera 1 \
  --min-brightness 15 \
  --max-brightness 140 \
  --min-sharpness 20 \
  --min-entropy 2.8 \
  --max-frames 5000 \
  --min-gap 2.0 \
  --sample-fps 1.0 \
  --n-bins 8 \
  --jobs 4

Rationale

  • Low brightness threshold (15): Accept dark frames (deep environment)
  • Moderate sharpness (20): Stable platform → expect reasonable sharpness
  • Moderate entropy (2.8): Organisms and geology provide texture
  • Larger min-gap (2.0s): Slow speed → larger gap to avoid redundancy
  • Typical grid (8 bins): Balanced diversity

Calibration Workflow

  1. Run calibrate on representative clip: 

    ./calibrate /data/sample_dive.mp4

  2. Check if median brightness < 50:

  3. Yes → Use low threshold (15–20)

  4. No → Increase threshold

  5. Check sharpness distribution:

  6. If p25 > 20 → Use strict threshold (25–30)

  7. If p25 < 20 → Use moderate threshold (18–22)

  8. Check entropy:

  9. Benthic surveys typically have high entropy (3.0–4.5)
  10. Threshold at p10–p20 (e.g., 2.8–3.2)

Mid-Water Plankton/Particle Imaging

Environment Characteristics

  • Moderate lighting (mix of ambient and artificial)
  • Sparse features (open water with occasional plankton/particles)
  • Low texture backgrounds (blue water dominates)
  • Moderate vehicle speed (0.5–1.5 m/s)
  • Some motion blur (particles moving, camera motion)

Typical Metric Distributions

brightness:  min=30  p5=50   median=90   p95=180  max=220
sharpness:   min=5   p5=12   median=28   p95=80   max=200
entropy:     min=1.5 p5=2.0  median=2.8  p95=4.5  max=5.5
motion:      min=1.0 p5=5.0  median=15   p95=35   max=70

./sample \
  --root-dir /data/midwater_survey \
  --camera 1 \
  --min-brightness 30 \
  --max-brightness 200 \
  --min-sharpness 15 \
  --min-entropy 2.0 \
  --max-frames 8000 \
  --min-gap 1.0 \
  --sample-fps 1.5 \
  --n-bins 8 \
  --jobs 4

Rationale

  • Moderate brightness range (30–200): Accept varied lighting
  • Relaxed sharpness (15): Motion blur is common, particles are small
  • Low entropy threshold (2.0): Blue water is common, don't over-reject
  • Larger budget (8000): Sparse features → need more frames to capture diversity
  • Smaller min-gap (1.0s): Moderate speed, plankton are sparse
  • Higher sample-fps (1.5): Catch brief plankton encounters

Calibration Workflow

  1. Run calibrate on clips with both plankton and empty water: 

    ./calibrate /data/plankton_clip.mp4 /data/empty_water.mp4

  2. Accept low entropy:

  3. Mid-water has inherently low texture (median entropy ~2.5–3.5)

  4. Threshold at p5 or p10 (e.g., 2.0–2.2)

  5. Relax sharpness if particles are small:

  6. Small features have low Laplacian variance

  7. Threshold at p10 (e.g., 12–18)

  8. Check pass rate:

  9. Target 50–70% (lower than benthic due to empty water rejection)

Shallow Reef Survey (<50m)

Environment Characteristics

  • High ambient light (sunlight penetration)
  • Rich texture (coral, algae, fish, substrate)
  • Rapid scene changes (fast vehicle speed over complex terrain)
  • Variable lighting (sun angle, shadows, reflections)
  • Generally sharp (good visibility, fast shutter speeds)

Typical Metric Distributions

brightness:  min=60  p5=90   median=140  p95=210  max=240
sharpness:   min=20  p5=45   median=85   p95=180  max=300
entropy:     min=3.0 p5=3.8  median=4.5  p95=5.8  max=6.5
motion:      min=5   p5=15   median=25   p95=55   max=90

./sample \
  --root-dir /data/reef_survey \
  --camera 1 \
  --min-brightness 50 \
  --max-brightness 220 \
  --min-sharpness 30 \
  --min-entropy 3.0 \
  --max-frames 5000 \
  --min-gap 1.5 \
  --sample-fps 2.0 \
  --n-bins 9 \
  --jobs 4

Rationale

  • Higher brightness threshold (50): Reject dark/shadowed frames
  • Reject overexposure (220): Sunlight can cause blown highlights
  • Stricter sharpness (30): Expect sharp images in clear water
  • Moderate entropy (3.0): Abundant texture (reject uniform water columns)
  • Higher sample-fps (2.0): Rapid scene changes → denser sampling
  • Finer grid (9 bins): High diversity → more granular binning

Calibration Workflow

  1. Run calibrate on representative reef clip: 

    ./calibrate /data/reef_transect.mp4

  2. Check for overexposure:

  3. If p95 > 230 → Lower max-brightness (200–220)

  4. Demand sharpness:

  5. Shallow water → expect good visibility

  6. Threshold at p20–p30 (e.g., 30–50)

  7. High entropy expected:

  8. Reef complexity → median entropy 4.0–5.0

  9. Threshold at p10 (e.g., 3.0–3.5)

  10. Check pass rate:

  11. Target 50–70% (high quality bias)

Fast Transect (High Vehicle Speed)

Environment Characteristics

  • Rapid movement (>1.5 m/s)
  • Motion blur common (unless very short shutter speed)
  • Rapid scene changes (diverse conditions within short time)
  • Variable lighting (rapid transitions between environments)

Typical Metric Distributions

brightness:  variable (depends on environments traversed)
sharpness:   min=3   p5=8    median=22   p95=65   max=150
entropy:     variable
motion:      min=10  p5=20   median=35   p95=60   max=100

./sample \
  --root-dir /data/fast_transect \
  --camera 1 \
  --min-brightness 20 \
  --max-brightness 230 \
  --min-sharpness 12 \
  --min-entropy 2.5 \
  --max-frames 10000 \
  --min-gap 0.5 \
  --sample-fps 2.0 \
  --n-bins 10 \
  --jobs 8

Rationale

  • Relaxed sharpness (12): Motion blur is pervasive at high speed
  • Small min-gap (0.5s): Fast movement → scene changes rapidly (0.75–1.5m between frames)
  • Higher sample-fps (2.0): Catch brief features
  • Larger budget (10000): High diversity → need more frames
  • Finer grid (10 bins): High environmental variability

Calibration Workflow

  1. Accept blur:
  2. Motion blur is unavoidable at high speed

  3. Threshold at p5 (e.g., 8–12)

  4. Check motion distribution:

  5. If median motion > 30 → vehicle is very fast

  6. Consider even smaller min-gap (0.3–0.5s)

  7. Use multiple calibration clips (different segments of transect): 

    ./calibrate /data/segment1.mp4 /data/segment2.mp4 /data/segment3.mp4

Static Benthic Lander

Environment Characteristics

  • Stationary platform (no vehicle motion)
  • Slow-changing scene (organisms enter/exit slowly)
  • Low motion (only subject movement)
  • Stable lighting (constant artificial light)
  • Long deployment (hours to days)

Typical Metric Distributions

brightness:  min=20  p5=30   median=55   p95=80   max=100
sharpness:   min=15  p5=30   median=55   p95=110  max=180
entropy:     min=2.5 p5=3.0  median=4.0  p95=5.5  max=6.2
motion:      min=0.1 p5=0.5  median=2.0  p95=10   max=40

./sample \
  --root-dir /data/lander_deployment \
  --camera 1 \
  --min-brightness 25 \
  --max-brightness 90 \
  --min-sharpness 25 \
  --min-entropy 3.0 \
  --max-frames 3000 \
  --min-gap 5.0 \
  --sample-fps 0.5 \
  --n-bins 7 \
  --jobs 4

Rationale

  • Large min-gap (5.0s): Static scene → large gap to avoid redundancy
  • Low sample-fps (0.5): Sparse sampling sufficient (scene changes slowly)
  • Stricter quality (sharpness 25, entropy 3.0): No excuse for poor quality (stable platform)
  • Smaller budget (3000): Limited diversity in static scene

Calibration Workflow

  1. Run calibrate on representative hour: 

    ./calibrate /data/lander_hour_12.mp4 --sample-fps 0.5

  2. Expect low motion:

  3. Median motion < 5 is typical

  4. Motion metric is less useful (consider removing from interest score)

  5. Demand quality:

  6. Stable platform → no motion blur

  7. Threshold sharpness at p25–p30 (e.g., 25–35)

  8. Large temporal gaps:

  9. Start with 5–10 seconds
  10. Increase if output frames look very similar

Low-Quality Optics (Blurry/Turbid)

Environment Characteristics

  • Poor optics (old camera, dirty lens, low-cost system)
  • High turbidity (suspended sediment, particles)
  • Pervasive blur (chronic defocus or motion blur)
  • Low sharpness across all frames

Typical Metric Distributions

brightness:  variable
sharpness:   min=2   p5=5    median=12   p95=30   max=80
entropy:     variable
motion:      variable

./sample \
  --root-dir /data/turbid_survey \
  --camera 1 \
  --min-brightness 20 \
  --max-brightness 230 \
  --min-sharpness 6 \
  --min-entropy 2.0 \
  --max-frames 5000 \
  --min-gap 1.0 \
  --sample-fps 1.0 \
  --n-bins 8 \
  --jobs 4

Rationale

  • Very relaxed sharpness (6): Accept best available (even if blurry)
  • Other thresholds moderate: Don't compound issues by being too strict overall

Calibration Workflow

  1. Run calibrate and check sharpness distribution: 

    ./calibrate /data/sample_turbid.mp4

  2. If median sharpness < 20:

  3. Lower threshold to p5 or p10 (e.g., 5–10)

  4. Accept that output will be blurry (best of bad data)

  5. Consider upstream fixes:

  6. Clean lens/dome
  7. Adjust focus
  8. Reduce vehicle speed (reduce motion blur)

  9. Wait for lower turbidity conditions

  10. Visual validation:

  11. Extract sample frames manually
  12. Confirm they are acceptable for intended use (even if blurry)

High-Quality Dataset (Archival)

Goal

Create a pristine dataset for long-term archival or publication:

  • Maximum quality
  • Lossless images
  • Small, curated set
  • Strict quality gates
./sample \
  --root-dir /data/archival_survey \
  --camera 1 \
  --min-brightness 40 \
  --max-brightness 200 \
  --min-sharpness 50 \
  --min-entropy 3.5 \
  --max-frames 1000 \
  --min-gap 3.0 \
  --sample-fps 1.0 \
  --n-bins 8 \
  --max-per-cell 5 \
  --format .png \
  --jobs 4

Rationale

  • Strict quality gates (sharpness 50, entropy 3.5): Demand excellence
  • Small budget (1000): Curated, not comprehensive
  • Low max-per-cell (5): Force diversity (avoid over-sampling common scenes)
  • PNG format: Lossless (no compression artifacts)
  • Larger min-gap (3.0s): Strong temporal separation

Workflow

  1. Run calibrate and choose strict thresholds:
  2. Use p50 or higher for all metrics

  3. Target 10–30% pass rate (very selective)

  4. Run sample with strict parameters

  5. Manual review:

  6. Visually inspect all 1000 frames
  7. Remove any marginal quality frames
  8. Final curated set: ~800–900 frames

Quick Preview (Speed-Priority)

Goal

Fast preview run to check data quality or test parameters:

  • Minimize runtime
  • Sacrifice completeness for speed
  • Quick iteration
./sample \
  --root-dir /data/preview \
  --camera 1 \
  --min-brightness 20 \
  --max-brightness 230 \
  --min-sharpness 15 \
  --min-entropy 2.5 \
  --max-frames 500 \
  --min-gap 2.0 \
  --sample-fps 0.5 \
  --n-bins 6 \
  --jobs 8 \
  --format .jpg

Rationale

  • Low sample-fps (0.5): Sparse sampling (50% reduction in examined frames)
  • Small budget (500): Fast extraction
  • Coarse grid (6 bins): Faster diversity selection
  • Many jobs (8): Maximize parallelism
  • JPEG output: Faster encoding

Workflow

  1. Run preview: 

    time ./sample ... --sample-fps 0.5 --max-frames 500
# ~2–5 minutes for typical dataset

  2. Inspect output frames:

  3. Check quality (are thresholds appropriate?)

  4. Check diversity (is grid capturing variety?)

  5. Adjust parameters and re-run full sampling: 

    ./sample ... --sample-fps 1.0 --max-frames 5000
# ~10–20 minutes

Tip: Caching makes re-runs very fast (only diversity selection and extraction re-run).

Summary Table

Scenario min-bright min-sharp min-entropy max-frames min-gap sample-fps
Deep benthic 15 20 2.8 5000 2.0 1.0
Mid-water plankton 30 15 2.0 8000 1.0 1.5
Shallow reef 50 30 3.0 5000 1.5 2.0
Fast transect 20 12 2.5 10000 0.5 2.0
Static lander 25 25 3.0 3000 5.0 0.5
Blurry/turbid 20 6 2.0 5000 1.0 1.0
Archival quality 40 50 3.5 1000 3.0 1.0
Quick preview 20 15 2.5 500 2.0 0.5

Next Steps