# whoigit/stingraytools architecture

> Architecture diagram of the GitHub repository whoigit/stingraytools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/whoigit/stingraytools
- Repository: https://github.com/whoigit/stingraytools

## Overview

StingrayTools processes Stingray cruise sensor data and camera metadata into dashboard-ready CSVs. The main workflow is sensor-file ingestion and calibration, time-binned cruise merging, frame-timestamp generation, and attaching media metadata; the companion image-analysis repository performs abundance updates to that same CSV. CTD reference downloads and other image utilities are additional capabilities. The graph follows README workflow statements and SOURCE INDEX references; unsampled subsystem internals and external service wiring are not expanded.

Main entry points: [`packages/stingraytools/src/stingray/sensors/merge.py`](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/sensors/merge.py) (Cruise sensor merge), [`packages/stingraytools/src/stingray/images/add_media.py`](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/images/add_media.py) (Attach media metadata), [`packages/stingraytools/src/stingray/cli/main.py`](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/cli/main.py) (Image commands), [`packages/stingraytools/src/stingray/ctd/download.py`](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/ctd/download.py) (CTD download command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Commands"]
  node_cli["Command interface<br/>[main.py]"]
  node_sensor_cmd["Sensor commands<br/>[sensors.py]"]
  node_media_cmd["Image commands<br/>[main.py]"]
  node_ctd_cmd["CTD download command<br/>[download.py]"]
end

subgraph group_sensors["Sensor processing"]
  node_merge["Cruise sensor merge<br/>[merge.py]"]
  node_ctd_sensor["CTD processing<br/>[ctd.py]"]
  node_fluoro["Fluorometer processing<br/>[fluorometer.py]"]
  node_par["PAR processing<br/>[par.py]"]
  node_suna["SUNA processing<br/>[suna.py]"]
  node_suna_io["SUNA calibration I/O<br/>[suna.py]"]
end

subgraph group_media["Camera and images"]
  node_timestamps["Frame timestamp builder"]
  node_add_media["Attach media metadata<br/>[add_media.py]"]
  node_abundance["Image abundance<br/>[abundance.py]"]
  node_image_tools["Image utilities"]
end

subgraph group_shared["Shared processing"]
  node_csv_io["CSV handling<br/>[csv.py]"]
  node_file_index["File indexing<br/>[indexing.py]"]
  node_columns["Dataset columns<br/>[columns.py]"]
  node_temporal["Time conversion<br/>[temporal.py]"]
  node_gridding["Time and position grids<br/>[gridding.py]"]
  node_spatial["Spatial utilities<br/>[spatial.py]"]
  node_profiles["Profile identification<br/>[identify.py]"]
end

subgraph group_reference["Reference data"]
end

node_user(("Operator"))
node_raw_sensors["Raw cruise sensors"]
node_sensor_csv["Cruise dashboard CSV"]
node_videos["Camera media files"]
node_frame_lists["Frame-list CSVs"]
node_enriched_csv["Media-enriched cruise CSV"]
node_analysis_repo["Companion analysis workflow"]
node_ctd_service["CTD reference source"]
node_ctd_data["CTD reference data"]

node_user -->|"runs"| node_cli
node_cli -->|"dispatches"| node_sensor_cmd
node_sensor_cmd -->|"invokes"| node_merge
node_raw_sensors -->|"supplies files"| node_merge
node_merge -->|"uses"| node_ctd_sensor
node_merge -->|"uses"| node_fluoro
node_merge -->|"uses"| node_par
node_merge -->|"uses"| node_suna
node_suna -->|"loads calibration"| node_suna_io
node_merge -->|"indexes files"| node_file_index
node_merge -->|"writes CSV"| node_csv_io
node_merge -->|"uses schema"| node_columns
node_merge -->|"converts times"| node_temporal
node_merge -->|"bins observations"| node_gridding
node_merge -->|"uses coordinates"| node_spatial
node_merge -->|"identifies profiles"| node_profiles
node_merge -->|"creates"| node_sensor_csv
node_user -->|"runs"| node_media_cmd
node_media_cmd -->|"invokes"| node_timestamps
node_videos -->|"provides media"| node_timestamps
node_timestamps -->|"creates"| node_frame_lists
node_media_cmd -->|"invokes"| node_add_media
node_sensor_csv -->|"provides cruise data"| node_add_media
node_frame_lists -->|"provides timestamps"| node_add_media
node_add_media -->|"updates CSV"| node_enriched_csv
node_enriched_csv -.->|"feeds abundance"| node_analysis_repo
node_analysis_repo -.->|"runs step"| node_abundance
node_abundance -->|"updates same CSV"| node_sensor_csv
node_user -->|"runs"| node_ctd_cmd
node_ctd_cmd -.->|"downloads from"| node_ctd_service
node_ctd_cmd -.->|"stores reference"| node_ctd_data

click node_cli "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/cli/main.py"
click node_sensor_cmd "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/cli/sensors.py"
click node_merge "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/sensors/merge.py"
click node_ctd_sensor "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/sensors/ctd.py"
click node_fluoro "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/sensors/fluorometer.py"
click node_par "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/sensors/par.py"
click node_suna "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/sensors/suna.py"
click node_suna_io "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/io/suna.py"
click node_csv_io "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/io/csv.py"
click node_file_index "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/io/indexing.py"
click node_columns "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/config/columns.py"
click node_temporal "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/utils/temporal.py"
click node_gridding "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/utils/gridding.py"
click node_spatial "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/utils/spatial.py"
click node_profiles "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/profiles/identify.py"
click node_media_cmd "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/cli/main.py"
click node_timestamps "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/images/build_frame_timestamps.py"
click node_add_media "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/images/add_media.py"
click node_abundance "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/images/abundance.py"
click node_image_tools "https://github.com/whoigit/stingraytools/tree/main/packages/stingraytools/src/stingray/images"
click node_ctd_cmd "https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/ctd/download.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_sensor_cmd,node_media_cmd,node_ctd_cmd toneBlue
class node_merge,node_ctd_sensor,node_fluoro,node_par,node_suna,node_suna_io toneAmber
class node_timestamps,node_add_media,node_abundance,node_image_tools toneMint
class node_csv_io,node_file_index,node_columns,node_temporal,node_gridding,node_spatial,node_profiles toneRose
class node_user,node_raw_sensors,node_sensor_csv,node_videos,node_frame_lists,node_enriched_csv,node_analysis_repo,node_ctd_service,node_ctd_data toneIndigo
```

## Components

### Commands

- [Command interface](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/cli/main.py): `packages/stingraytools/src/stingray/cli/main.py`
- [Sensor commands](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/cli/sensors.py): `packages/stingraytools/src/stingray/cli/sensors.py`
- [Image commands](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/cli/main.py): `packages/stingraytools/src/stingray/cli/main.py`
- [CTD download command](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/ctd/download.py): `packages/stingraytools/src/stingray/ctd/download.py`

### Sensor processing

- [Cruise sensor merge](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/sensors/merge.py): `packages/stingraytools/src/stingray/sensors/merge.py`
- [CTD processing](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/sensors/ctd.py): `packages/stingraytools/src/stingray/sensors/ctd.py`
- [Fluorometer processing](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/sensors/fluorometer.py): `packages/stingraytools/src/stingray/sensors/fluorometer.py`
- [PAR processing](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/sensors/par.py): `packages/stingraytools/src/stingray/sensors/par.py`
- [SUNA processing](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/sensors/suna.py): `packages/stingraytools/src/stingray/sensors/suna.py`
- [SUNA calibration I/O](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/io/suna.py): `packages/stingraytools/src/stingray/io/suna.py`

### Camera and images

- [Frame timestamp builder](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/images/build_frame_timestamps.py): `packages/stingraytools/src/stingray/images/build_frame_timestamps.py`
- [Attach media metadata](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/images/add_media.py): `packages/stingraytools/src/stingray/images/add_media.py`
- [Image abundance](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/images/abundance.py): `packages/stingraytools/src/stingray/images/abundance.py`
- [Image utilities](https://github.com/whoigit/stingraytools/tree/main/packages/stingraytools/src/stingray/images): `packages/stingraytools/src/stingray/images`

### Shared processing

- [CSV handling](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/io/csv.py): `packages/stingraytools/src/stingray/io/csv.py`
- [File indexing](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/io/indexing.py): `packages/stingraytools/src/stingray/io/indexing.py`
- [Dataset columns](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/config/columns.py): `packages/stingraytools/src/stingray/config/columns.py`
- [Time conversion](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/utils/temporal.py): `packages/stingraytools/src/stingray/utils/temporal.py`
- [Time and position grids](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/utils/gridding.py): `packages/stingraytools/src/stingray/utils/gridding.py`
- [Spatial utilities](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/utils/spatial.py): `packages/stingraytools/src/stingray/utils/spatial.py`
- [Profile identification](https://github.com/whoigit/stingraytools/blob/main/packages/stingraytools/src/stingray/profiles/identify.py): `packages/stingraytools/src/stingray/profiles/identify.py`

### Other components

- **Operator**
- **Raw cruise sensors**
- **Cruise dashboard CSV**
- **Camera media files**
- **Frame-list CSVs**
- **Media-enriched cruise CSV**
- **Companion analysis workflow**
- **CTD reference source**
- **CTD reference data**

## Connections

- Operator → Command interface: runs (evidence: `README.md`)
- Command interface → Sensor commands: dispatches (evidence: `packages/stingraytools/src/stingray/cli/main.py`)
- Sensor commands → Cruise sensor merge: invokes (evidence: `packages/stingraytools/src/stingray/cli/sensors.py`)
- Raw cruise sensors → Cruise sensor merge: supplies files (evidence: `packages/stingraytools/src/stingray/sensors/merge.py`)
- Cruise sensor merge → CTD processing: uses (evidence: `packages/stingraytools/src/stingray/sensors/merge.py`)
- Cruise sensor merge → Fluorometer processing: uses (evidence: `packages/stingraytools/src/stingray/sensors/merge.py`)
- Cruise sensor merge → PAR processing: uses (evidence: `packages/stingraytools/src/stingray/sensors/merge.py`)
- Cruise sensor merge → SUNA processing: uses (evidence: `packages/stingraytools/src/stingray/sensors/merge.py`)
- SUNA processing → SUNA calibration I/O: loads calibration (evidence: `packages/stingraytools/src/stingray/sensors/suna.py`)
- Cruise sensor merge → File indexing: indexes files (evidence: `packages/stingraytools/src/stingray/sensors/merge.py`)
- Cruise sensor merge → CSV handling: writes CSV (evidence: `packages/stingraytools/src/stingray/sensors/merge.py`)
- Cruise sensor merge → Dataset columns: uses schema (evidence: `packages/stingraytools/src/stingray/sensors/merge.py`)
- Cruise sensor merge → Time conversion: converts times (evidence: `packages/stingraytools/src/stingray/sensors/merge.py`)
- Cruise sensor merge → Time and position grids: bins observations (evidence: `packages/stingraytools/src/stingray/sensors/merge.py`)
- Cruise sensor merge → Spatial utilities: uses coordinates (evidence: `packages/stingraytools/src/stingray/sensors/merge.py`)
- Cruise sensor merge → Profile identification: identifies profiles (evidence: `packages/stingraytools/src/stingray/sensors/merge.py`)
- Cruise sensor merge → Cruise dashboard CSV: creates (evidence: `README.md`)
- Operator → Image commands: runs (evidence: `README.md`)
- Image commands → Frame timestamp builder: invokes (evidence: `README.md`)
- Camera media files → Frame timestamp builder: provides media (evidence: `README.md`)
- Frame timestamp builder → Frame-list CSVs: creates (evidence: `README.md`)
- Image commands → Attach media metadata: invokes (evidence: `README.md`)
- Cruise dashboard CSV → Attach media metadata: provides cruise data (evidence: `README.md`)
- Frame-list CSVs → Attach media metadata: provides timestamps (evidence: `README.md`)
- Attach media metadata → Media-enriched cruise CSV: updates CSV (evidence: `README.md`)
- Media-enriched cruise CSV → Companion analysis workflow: feeds abundance (evidence: `README.md`)
- Companion analysis workflow → Image abundance: runs step (evidence: `README.md`)
- Image abundance → Cruise dashboard CSV: updates same CSV (evidence: `README.md`)
- Operator → CTD download command: runs (evidence: `README.md`)
- CTD download command → CTD reference source: downloads from
- CTD download command → CTD reference data: stores reference (evidence: `README.md`)
