# cbassa/stvid architecture

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

- Interactive diagram: https://gitdiagram.com/cbassa/stvid
- Repository: https://github.com/cbassa/stvid

## Overview

1. **What this repository is**
   STVID is a small, script-driven pipeline for satellite-observing nights: it acquires camera video, turns it into FITS-based observation products, then measures and identifies satellite tracks against orbital catalogs.

2. **Top-level execution model**
   The architecture is centered around three standalone entry points:
   - `acquire.py` for live camera capture
   - `process.py` for post-capture analysis
   - `update_tle.py` for refreshing orbital prediction data  
   These are coordinated through a shared `configuration.ini` and a common observation/TLE file layout.

3. **Acquisition subsystem**
   `acquire.py` is the ingest boundary to the outside world. It talks to the configured camera type (`OpenCV`, `ZWO ASI`, or Raspberry Pi HQ camera) and writes observation data into the configured `observations_path`. The repo also includes `shutter_control.py` and `stvid/shutter.py`, which suggest a hardware-control path for opening/closing a physical shutter during observing runs.

4. **Processing subsystem**
   `process.py` is the offline analysis boundary. It consumes the FITS files produced by acquisition and drives the scientific workflow: image preparation, star detection, astrometric calibration, satellite detection, and identification. This is where raw frames become measured events.

5. **Image and measurement helpers**
   The `stvid` package is the core library used by the scripts. The most relevant modules are:
   - `fourframe.py` for the “maximum temporal pixel” compression / four-frame observation products
   - `extract.py` for integrating with star/feature extraction
   - `stio.py` for file I/O and observation serialization
   - `utils.py` for shared helpers  
   These modules form the internal data plumbing between capture, calibration, and track detection.

6. **Astrometry and star catalog calibration**
   Astrometric calibration is handled in `stvid/astrometry.py` and `stvid/calibration.py`, with star-related support in `stvid/stars.py`. The repository bundles a `data/tyc2.fits` star catalog, while the README says it also depends on `astrometry.net` index files for initial plate solving. This subsystem turns pixel positions into sky coordinates so satellite detections can be expressed as real RA/Dec and time metadata.

7. **Satellite detection and identification**
   Satellite track detection is centered on `stvid/satellite.py`. The README indicates the detection engine uses a 3D Hough transform workflow, which is implemented externally by `hough3dlines`. Once a track is detected, it is matched against predicted satellite positions computed from TLEs via `satpredict`. This is the main scientific matching boundary: observed track vs. catalog prediction.

8. **Orbital catalog management**
   `update_tle.py` refreshes the prediction data used by the processor. STVID supports multiple catalogs with different roles: Space-Track master catalog, classified objects, integrated elements, and supplemental Starlink/OneWeb TLEs. These are stored under the configured `tlepath` and then consumed by processing for prediction and identification.

9. **External tools that shape the architecture**
   STVID is not self-contained; it depends on several external executables that define major subsystem boundaries:
   - `source-extractor` for star detection and instrumental photometry
   - `astrometry.net` for initial plate solving
   - `hough3dlines` for line-track detection in time-series imagery
   - `satpredict` for fast orbit-based position prediction  
   The Python code mainly orchestrates these tools and interprets their outputs.

10. **File and data artifacts**
   The repo includes config templates and algorithm-specific support files:
   - `configuration.ini-dist` for runtime configuration
   - `source-extractor/default.*` for SExtractor behavior
   - `data/tyc2.fits` as a bundled catalog
   - `img/` for documentation imagery  
   Observation output, TLE catalogs, and derived measurement products are expected to live outside the repo, in user-configured directories.

11. **Operational boundary between live and offline work**
   Live observation and post-processing are deliberately separated. Acquisition can run continuously on a Linux desktop or SBC, while processing can be executed later on stored FITS files. That separation is important for an architecture diagram: the camera/shutter path is real-time, but the scientific analysis path is batch-oriented.

12. **What to emphasize in a diagram**
   The most important arrows are:
   camera hardware → `acquire.py` → FITS observations → `process.py` → calibrated measurements / satellite IDs / IOD output  
   and
   external TLE sources → `update_tle.py` → local TLE cache → `process.py` prediction matching  
   The external astronomy tools sit beside the Python pipeline as required processing engines rather than internal libraries.

Main entry points: [`process.py`](https://github.com/cbassa/stvid/blob/main/process.py) (Process), [`acquire.py`](https://github.com/cbassa/stvid/blob/main/acquire.py) (Acquire), [`stvid/satellite.py`](https://github.com/cbassa/stvid/blob/main/stvid/satellite.py) (Satellite), [`stvid/utils.py`](https://github.com/cbassa/stvid/blob/main/stvid/utils.py) (Utils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_entry["Entry points"]
  node_n_acquire["Acquire<br/>script<br/>[acquire.py]"]
  node_n_process["Process<br/>script<br/>[process.py]"]
  node_n_update_tle["Update TLE<br/>script<br/>[update_tle.py]"]
end

subgraph group_grp_core["Core library"]
  node_n_stio["IO layer<br/>[stio.py]"]
  node_n_fourframe["Four-frame<br/>[fourframe.py]"]
  node_n_extract["Extract<br/>[extract.py]"]
  node_n_astrometry["Astrometry<br/>[astrometry.py]"]
  node_n_calibration["Calibration<br/>[calibration.py]"]
  node_n_stars["Stars<br/>[stars.py]"]
  node_n_satellite["Satellite<br/>[satellite.py]"]
  node_n_utils["Utils<br/>[utils.py]"]
  node_n_shutter_mod["Shutter<br/>[shutter.py]"]
end

subgraph group_grp_external["External engines"]
  node_n_camera(("Camera<br/>hardware"))
  node_n_shutter_hw(("Shutter hw<br/>hardware"))
  node_n_sextractor["Source Extractor<br/>external tool<br/>[default.sex]"]
  node_n_astrom_net["Astrometry.net<br/>external tool"]
  node_n_hough3d["Hough3DLines<br/>external tool"]
  node_n_satpredict["Satpredict<br/>external tool"]
end

subgraph group_grp_data["Data and config"]
  node_n_config["Config template"]
  node_n_tyc2[("TYC2 catalog<br/>[tyc2.fits]")]
  node_n_tle_cache[("TLE cache<br/>data store")]
  node_n_obs_store[("Observations<br/>data store")]
end

node_n_camera -->|"frames"| node_n_acquire
node_n_shutter_hw -->|"actuates"| node_n_shutter_mod
node_n_shutter_mod -->|"gates"| node_n_acquire
node_n_acquire -->|"builds"| node_n_fourframe
node_n_acquire -->|"writes"| node_n_stio
node_n_stio -->|"stores"| node_n_obs_store
node_n_process -->|"reads"| node_n_stio
node_n_process -->|"detects"| node_n_extract
node_n_process -->|"calibrates"| node_n_calibration
node_n_process -->|"measures"| node_n_satellite
node_n_extract -->|"calls"| node_n_sextractor
node_n_calibration -->|"solves"| node_n_astrometry
node_n_calibration -->|"uses"| node_n_stars
node_n_astrometry -->|"delegates"| node_n_astrom_net
node_n_stars -->|"catalog"| node_n_tyc2
node_n_satellite -->|"detects"| node_n_hough3d
node_n_satellite -->|"matches"| node_n_satpredict
node_n_update_tle -->|"refreshes"| node_n_tle_cache
node_n_tle_cache -->|"predicts"| node_n_process
node_n_config -->|"configures"| node_n_acquire
node_n_config -->|"configures"| node_n_process
node_n_config -->|"configures"| node_n_update_tle
node_n_utils -.->|"helpers"| node_n_acquire
node_n_utils -.->|"helpers"| node_n_process
node_n_utils -.->|"helpers"| node_n_satellite

click node_n_acquire "https://github.com/cbassa/stvid/blob/main/acquire.py"
click node_n_process "https://github.com/cbassa/stvid/blob/main/process.py"
click node_n_update_tle "https://github.com/cbassa/stvid/blob/main/update_tle.py"
click node_n_config "https://github.com/cbassa/stvid/blob/main/configuration.ini-dist"
click node_n_tyc2 "https://github.com/cbassa/stvid/blob/main/data/tyc2.fits"
click node_n_stio "https://github.com/cbassa/stvid/blob/main/stvid/stio.py"
click node_n_fourframe "https://github.com/cbassa/stvid/blob/main/stvid/fourframe.py"
click node_n_extract "https://github.com/cbassa/stvid/blob/main/stvid/extract.py"
click node_n_astrometry "https://github.com/cbassa/stvid/blob/main/stvid/astrometry.py"
click node_n_calibration "https://github.com/cbassa/stvid/blob/main/stvid/calibration.py"
click node_n_stars "https://github.com/cbassa/stvid/blob/main/stvid/stars.py"
click node_n_satellite "https://github.com/cbassa/stvid/blob/main/stvid/satellite.py"
click node_n_utils "https://github.com/cbassa/stvid/blob/main/stvid/utils.py"
click node_n_shutter_mod "https://github.com/cbassa/stvid/blob/main/stvid/shutter.py"
click node_n_sextractor "https://github.com/cbassa/stvid/blob/main/source-extractor/default.sex"

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_n_acquire,node_n_process,node_n_update_tle toneBlue
class node_n_stio,node_n_fourframe,node_n_extract,node_n_astrometry,node_n_calibration,node_n_stars,node_n_satellite,node_n_utils,node_n_shutter_mod toneAmber
class node_n_camera,node_n_shutter_hw,node_n_sextractor,node_n_astrom_net,node_n_hough3d,node_n_satpredict toneMint
class node_n_config,node_n_tyc2,node_n_tle_cache,node_n_obs_store toneRose
```

## Components

### Entry points

Standalone scripts that start acquisition, processing, and catalog refresh.

- [Acquire](https://github.com/cbassa/stvid/blob/main/acquire.py): script · Live capture entry point for camera ingest and observing runs. · `acquire.py`
- [Process](https://github.com/cbassa/stvid/blob/main/process.py): script · Offline analysis entry point for FITS-based satellite measurement. · `process.py`
- [Update TLE](https://github.com/cbassa/stvid/blob/main/update_tle.py): script · Refreshes orbital prediction data for later matching. · `update_tle.py`

### Core library

Shared STVID modules that move data through capture, calibration, and track analysis.

- [IO layer](https://github.com/cbassa/stvid/blob/main/stvid/stio.py): module · Observation serialization and file layout handling. · `stvid/stio.py`
- [Four-frame](https://github.com/cbassa/stvid/blob/main/stvid/fourframe.py): module · Temporal-pixel compression and observation product handling. · `stvid/fourframe.py`
- [Extract](https://github.com/cbassa/stvid/blob/main/stvid/extract.py): module · Wrapper for star and feature extraction steps. · `stvid/extract.py`
- [Astrometry](https://github.com/cbassa/stvid/blob/main/stvid/astrometry.py): module · Plate solving and sky-coordinate transformation support. · `stvid/astrometry.py`
- [Calibration](https://github.com/cbassa/stvid/blob/main/stvid/calibration.py): module · Astrometric calibration orchestration and refinement. · `stvid/calibration.py`
- [Stars](https://github.com/cbassa/stvid/blob/main/stvid/stars.py): module · Star-related support for calibration and matching. · `stvid/stars.py`
- [Satellite](https://github.com/cbassa/stvid/blob/main/stvid/satellite.py): module · Satellite track detection and identification logic. · `stvid/satellite.py`
- [Utils](https://github.com/cbassa/stvid/blob/main/stvid/utils.py): module · Shared helper functions used across the pipeline. · `stvid/utils.py`
- [Shutter](https://github.com/cbassa/stvid/blob/main/stvid/shutter.py): module · Hardware shutter control integration. · `stvid/shutter.py`

### External engines

Required hardware and third-party tools that define major subsystem boundaries.

- **Camera**: hardware · Configured live camera source for acquisition.
- **Shutter hw**: hardware · Physical shutter actuator used during observing runs.
- [Source Extractor](https://github.com/cbassa/stvid/blob/main/source-extractor/default.sex): external tool · Third-party star detection and photometry engine. · `source-extractor/default.sex`
- **Astrometry.net**: external tool · External plate-solving engine and index set.
- **Hough3DLines**: external tool · External line-track detector for satellite trails.
- **Satpredict**: external tool · External orbit prediction engine for identification matching.

### Data and config

Bundled catalog and runtime configuration artifacts.

- [Config template](https://github.com/cbassa/stvid/blob/main/configuration.ini-dist): config · Default runtime configuration for paths, devices, and processing options. · `configuration.ini-dist`
- [TYC2 catalog](https://github.com/cbassa/stvid/blob/main/data/tyc2.fits): catalog · Bundled star catalog used for calibration support. · `data/tyc2.fits`
- **TLE cache**: data store · Local orbital catalog storage consumed by processing.
- **Observations**: data store · Configured output location for captured and derived observation files.

## Connections

- Camera → Acquire: frames · Live video is captured from the configured camera.
- Shutter hw → Shutter: actuates · Physical shutter control is driven through the shutter module.
- Shutter → Acquire: gates · Acquisition can open or close the shutter during observing runs.
- Acquire → Four-frame: builds · Captured frames are converted into four-frame observation products.
- Acquire → IO layer: writes · Observation outputs are written through the shared I/O layer.
- IO layer → Observations: stores · Output files land in the configured observation directory.
- Process → IO layer: reads · Processing consumes previously written observation files.
- Process → Extract: detects · Feature and star extraction begins the analysis workflow.
- Process → Calibration: calibrates · Astrometric calibration refines sky positions.
- Process → Satellite: measures · Satellite tracks are detected and identified.
- Extract → Source Extractor: calls · Star detection is delegated to Source Extractor.
- Calibration → Astrometry: solves · Calibration depends on astrometric plate solving.
- Calibration → Stars: uses · Star support data informs calibration refinement.
- Astrometry → Astrometry.net: delegates · Initial plate solving is handled by astrometry.net.
- Stars → TYC2 catalog: catalog · The bundled TYC2 catalog supports star matching.
- Satellite → Hough3DLines: detects · Track finding relies on the external 3D Hough engine.
- Satellite → Satpredict: matches · Detected tracks are compared with predicted satellite positions.
- Update TLE → TLE cache: refreshes · TLE update populates the local prediction cache.
- TLE cache → Process: predicts · Processing uses cached TLEs for identification and matching.
- Config template → Acquire: configures · Acquisition settings are driven by the shared configuration.
- Config template → Process: configures · Processing behavior and paths are driven by the shared configuration.
- Config template → Update TLE: configures · Catalog refresh uses the shared configuration.
- Utils → Acquire: helpers · Shared helper code supports the entry points.
- Utils → Process: helpers · Shared helper code supports the analysis pipeline.
- Utils → Satellite: helpers · Satellite analysis reuses common utilities.
