StingrayTools

StingrayTools is the reusable processing package for Stingray sensor data, camera metadata, image abundance, and CTD reference data.

Responsibilities

• sensors: merge calibrated sensor observations into cruise CSV files.
• images: build frame timestamps, attach camera metadata, and compute image abundance.
• ctd: download and compile CTD reference data.
• shared utilities: CSV handling, time grids, profiles, and statistics.

Video inference and job orchestration are maintained in the companion stingray-image-analysis repository. The Dash application is maintained in stingray-dashboard.

Data contract

Dashboard-ready cruise files use one dataset directory per platform/project:

dashboard_data/
  data/
    <platform_project>/
      <cruise>.csv
  media_list/
    <camera_stream>/
      <cruise>_frame_list_fast.csv

Sensor processing creates the cruise CSV. Image abundance updates that same CSV with abundance columns; it does not create a separate dashboard dataset.

Installation

Install only the required dependency group:

pip install "stingraytools[sensors] @ git+https://github.com/WHOIGit/stingraytools.git"
pip install "stingraytools[images] @ git+https://github.com/WHOIGit/stingraytools.git"
pip install "stingraytools[ctd] @ git+https://github.com/WHOIGit/stingraytools.git"
pip install "stingraytools[abundance] @ git+https://github.com/WHOIGit/stingraytools.git"

Commands

Merge one cruise of sensor data:

stingray sensors merge \
  --work-dir /path/to/stingray/data \
  --cruise CRUISE_ID \
  --start START_DATE \
  --end END_DATE \
  --cal-year CALIBRATION_YEAR \
  --time-bin-seconds BIN_WIDTH_SECONDS

Build camera frame timestamps:

stingray images frame-timestamp \
  --work-dir /path/to/stingray/data \
  --cruise CRUISE_ID \
  --media-dir /path/to/CAMERA_MEDIA_DIR \
  --out-dir /path/to/stingray/data/media_list/CAMERA_STREAM

Attach camera metadata to a cruise CSV:

stingray images add-media \
  /path/to/stingray/data/dashboard_data/data/DATASET/CRUISE.csv \
  --work-dir /path/to/stingray/data \
  --cruise CRUISE_ID \
  --media-list-dirs /path/to/stingray/data/media_list/CAMERA_STREAM

Download CTD reference data:

stingray ctd download \
  --work-dir /path/to/stingray/data \
  --skip-existing

Run the companion video and abundance workflow from its repository. Its abundance step reads the sensor CSV and writes the updated product to the same path.

stingray images abundance --detections accepts detections from any model in one of these forms:

• a Parquet or CSV table with media, frame, class (or class_id with --class-map-csv) and an optional score; or
• standard COCO JSON whose images are named <media>_<frame>.png.

frame is the 0-based source-video frame, matching the frame list. Boxes without a score are manual and always counted. A COCO file counts only the frames it lists. Skipped rows and frames are logged and, with --issues-csv, written to a CSV.

Use command help for complete options:

stingray --help
stingray sensors --help
stingray images --help

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest packages/stingraytools/tests

License and citation

StingrayTools is distributed under the MIT License. See LICENSE.

Please cite CITATION.cff.