How cbassa/stvid works
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 Process · acquire.py Acquire · satellite.py Satellite · utils.py Utils
Components 22
Entry points
Standalone scripts that start acquisition, processing, and catalog refresh.
- Acquire · Live capture entry point for camera ingest and observing runs.
acquire.py - Process · Offline analysis entry point for FITS-based satellite measurement.
process.py - Update TLE · 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 · Observation serialization and file layout handling.
stvid/stio.py - Four-frame · Temporal-pixel compression and observation product handling.
stvid/fourframe.py - Extract · Wrapper for star and feature extraction steps.
stvid/extract.py - Astrometry · Plate solving and sky-coordinate transformation support.
stvid/astrometry.py - Calibration · Astrometric calibration orchestration and refinement.
stvid/calibration.py - Stars · Star-related support for calibration and matching.
stvid/stars.py - Satellite · Satellite track detection and identification logic.
stvid/satellite.py - Utils · Shared helper functions used across the pipeline.
stvid/utils.py - Shutter · Hardware shutter control integration.
stvid/shutter.py
External engines
Required hardware and third-party tools that define major subsystem boundaries.
- Camera · Configured live camera source for acquisition.
- Shutter hw · Physical shutter actuator used during observing runs.
- Source Extractor · Third-party star detection and photometry engine.
source-extractor/default.sex - Astrometry.net · External plate-solving engine and index set.
- Hough3DLines · External line-track detector for satellite trails.
- Satpredict · External orbit prediction engine for identification matching.
Data and config
Bundled catalog and runtime configuration artifacts.
- Config template · Default runtime configuration for paths, devices, and processing options.
configuration.ini-dist - TYC2 catalog · Bundled star catalog used for calibration support.
data/tyc2.fits - TLE cache · Local orbital catalog storage consumed by processing.
- Observations · Configured output location for captured and derived observation files.
Connections 25
- 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.