# jamiesmith/astrophotography architecture

> Architecture diagram of the GitHub repository jamiesmith/astrophotography, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jamiesmith/astrophotography
- Repository: https://github.com/jamiesmith/astrophotography

## Overview

##### Project Type and Purpose
- This is an open-source tool suite for astrophotography:
– PySkyX: A Python package plus command-line scripts to control TheSkyX telescope software, cameras (flats, darks), flip-flat hardware, data logging and analysis.
– Automation: Shell/AWK/PowerShell/JavaScript scripts to automate image import, summarization, remote control of hardware (Eagle controllers), and integration with external storage (Dropbox, mirrors).

##### File Structure
Top-level:
- PySkyX/
– library/: Core Python modules for communicating with TheSkyX (PySkyX_ks.py, PySkyX_jrs.py), GUI (RT_GUI.py), flat-field controller (flatman_ctl.py).
– examples/: Sample Python scripts showing common tasks (take_darks, dump_stars, reduce_ds).
– documentation/: User guides (PDFs).
– scripts at root: High-level Python entry points (take_flats.py, characterize_flats.py, iterate_flats.py, etc.).
– config CSVs: per_filter_exposure_settings.csv, per_filter_flatman_settings.csv.
- automation/
– shell/awk scripts: image summaries, boltwood weather station parsing, JPEG shrinking, Dropbox syncing.
– PowerShell: Eagle hardware port on/off.
– theSkyX-JavaScript/: Telescope control macros for ScriptTheSkyX.

##### Extract Insights from README
- Confirms this is a toolkit for astrophotography workflows.

##### Main Components & Their Interactions
A. Python SDK & CLI (PySkyX)
- Core modules (library/) ↔ TheSkyX COM API
- CLI scripts (take_flats.py, take_darks.py, etc.) → invoke core modules → control camera/flat hardware → produce FITS images + logs
- Examples → illustrate module usage → no external dependencies beyond Python & TheSkyX
- Configuration CSVs loaded by CLI scripts to parameterize exposure settings
B. Automation Scripts
- Shell/AWK scripts → process images and logs → generate CSV/HTML summaries
- PowerShell → send commands to Eagle controllers → turn flip-flat on/off
- JS macros → run inside TheSkyX Script Editor → extend telescope control capabilities
- Integration with external services: Dropbox, file mirrors, local storage
C. External Systems
- TheSkyX telescope control software (COM interface)
- Camera hardware (flats, darks)
- Flip-flat device via Eagle controllers
- Storage & network: local disks, Dropbox, mirror servers

##### Architectural Patterns & Principles
- Modular CLI: each Python script is a thin wrapper around core library modules.
- Separation of concerns:
– library/ handles API communication
– CLI scripts handle user workflow
– examples showcase usage
– automation/ handles post-processing & infrastructure tasks
- Configuration via CSVs to avoid hard-coding exposure settings
- Polyglot automation: AWK, shell, PowerShell, JS—each chosen to best interact with its target environment

## Diagram (Mermaid)

```mermaid
graph TB
    %% Python Layer
    subgraph "PySkyX SDK & CLI" 
        direction TB
        PyCore["Core Library Modules"]:::python
        subgraph "CLI Scripts"
            direction TB
            CharFlats["characterize_flats.py"]:::python
            IterateFlats["iterate_flats.py"]:::python
            TakeFlats["take_flats.py"]:::python
            TakeFlatsFM["take_flats_fm.py"]:::python
            TakeDarks["take_darks.py"]:::python
            CloseTurnOff["close-and-turn-off-flipflat.py"]:::python
            TestFlipflat["test-flipflat.py"]:::python
        end
        Examples["Examples"]:::python
        ConfigExposure["per_filter_exposure_settings.csv"]:::datasource
        ConfigFlatman["per_filter_flatman_settings.csv"]:::datasource
        Documentation["Documentation"]:::datasource
        OldScripts["Legacy/Deprecated Scripts"]:::python
    end

    %% Automation Layer
    subgraph "Automation Scripts" 
        direction TB
        subgraph "Shell & AWK"
            direction TB
            AstroSummary["astroImageSummary.sh"]:::automation
            ImportAstro["importAstroPhotos.sh"]:::automation
            ImportDropbox["importPhotosFromDropbox.sh"]:::automation
            ImportMirror["importPhotosFromMirror.sh"]:::automation
            SyncPhotos["syncPhotos.sh"]:::automation
            ShrinkJPEG["shrinkJPEG.sh"]:::automation
            ParseBoltwood["ParseBoltwood.awk"]:::automation
            Boltwood2CSV["boltwood2csv.awk"]:::automation
            Boltwood2HTML["boltwood2html.awk"]:::automation
            SummaryBoltwood["summaryboltwood2csv.awk"]:::automation
            SummarizeImages["summarizeAstroImages.sh"]:::automation
        end
        subgraph "PowerShell"
            direction TB
            EaglePS1["*.ps1 Eagle Controllers"]:::automation
        end
        subgraph "Windows Batch"
            direction TB
            OpenFlipFlatBAT["open-flip-flat.bat"]:::automation
            OpenFlipFlatCMD["open-flip-flat.cmd"]:::automation
            CloseFlipFlatBAT["close-flip-flat.bat"]:::automation
        end
        subgraph "TheSkyX JS Macros"
            direction TB
            CaptureFlatsJS["CaptureFlats.js"]:::automation
            CommonUtilsJS["CommonUtils.js"]:::automation
            FilterFocusOffsetsJS["FilterFocusOffsets.js"]:::automation
            ImageRunTemplateJS["ImageRunTemplate.js"]:::automation
            MessierMarathonJS["MessierMarathon.js"]:::automation
            UnguidedDitherJS["UnguidedDither.js"]:::automation
            UnguidedDitherHDRJS["UnguidedDitherHDR.js"]:::automation
            AutoflatsJS["autoflats.js"]:::automation
        end
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        TheSkyXAPI["TheSkyX COM API"]:::external
        CameraHardware["Camera Hardware"]:::external
        FlipFlatDevice["Flip-Flat Device (Eagle)"]:::external
        Dropbox["Dropbox/Cloud"]:::external
        MirrorServer["Mirror Server"]:::external
        LocalDisk["Local Storage"]:::external
    end

    %% Data Stores
    ImageRepo["FITS Images & Logs"]:::datasource

    %% Flows
    TakeFlats -->|"invoke"| PyCore
    TakeDarks -->|"invoke"| PyCore
    CharFlats -->|"invoke"| PyCore
    IterateFlats -->|"invoke"| PyCore
    TestFlipflat -->|"invoke"| PyCore
    CloseTurnOff -->|"invoke"| PyCore

    PyCore -->|"COM calls"| TheSkyXAPI
    TheSkyXAPI -->|"control camera"| CameraHardware
    TheSkyXAPI -->|"control flip-flat"| FlipFlatDevice
    CameraHardware -->|"produce images & logs"| ImageRepo

    ImageRepo -->|"process logs/images"| AstroSummary
    ImageRepo -->|"process images"| ShrinkJPEG
    ImageRepo -->|"summarize"| SummarizeImages
    ImageRepo -->|"import photos"| ImportAstro
    ImportAstro -->|"sync to"| LocalDisk
    ImportDropbox -->|"sync to"| LocalDisk
    ImportMirror -->|"sync to"| LocalDisk
    SyncPhotos -->|"sync between"| LocalDisk
    AstroSummary -->|"generate boltwood summary"| ParseBoltwood
    ParseBoltwood --> Boltwood2CSV --> Boltwood2HTML --> SummaryBoltwood

    SummarizeImages -->|"upload"| Dropbox
    SummarizeImages -->|"upload"| MirrorServer

    EaglePS1 -->|"power control"| FlipFlatDevice
    OpenFlipFlatBAT -->|"open relay"| FlipFlatDevice
    CloseFlipFlatBAT -->|"close relay"| FlipFlatDevice

    %% JS Macros run inside TheSkyX
    CaptureFlatsJS --> TheSkyXAPI
    CommonUtilsJS --> TheSkyXAPI
    FilterFocusOffsetsJS --> TheSkyXAPI
    ImageRunTemplateJS --> TheSkyXAPI
    MessierMarathonJS --> TheSkyXAPI
    UnguidedDitherJS --> TheSkyXAPI
    UnguidedDitherHDRJS --> TheSkyXAPI
    AutoflatsJS --> TheSkyXAPI

    Examples -->|"demonstrate usage"| PyCore
    Examples -->|"run CLI scripts"| TakeFlats

    Documentation -->|"user guide"| Examples

    ConfigExposure --> TakeFlats
    ConfigFlatman --> TakeFlatsFM

    OldScripts -->|deprecated| PyCore

    %% Click Events
    click PyCore "https://github.com/jamiesmith/astrophotography/tree/master/PySkyX/library/"
    click CharFlats "https://github.com/jamiesmith/astrophotography/blob/master/PySkyX/characterize_flats.py"
    click IterateFlats "https://github.com/jamiesmith/astrophotography/blob/master/PySkyX/iterate_flats.py"
    click TakeFlats "https://github.com/jamiesmith/astrophotography/blob/master/PySkyX/take_flats.py"
    click TakeFlatsFM "https://github.com/jamiesmith/astrophotography/blob/master/PySkyX/take_flats_fm.py"
    click TakeDarks "https://github.com/jamiesmith/astrophotography/blob/master/PySkyX/take_darks.py"
    click CloseTurnOff "https://github.com/jamiesmith/astrophotography/blob/master/PySkyX/close-and-turn-off-flipflat.py"
    click TestFlipflat "https://github.com/jamiesmith/astrophotography/blob/master/PySkyX/test-flipflat.py"
    click Examples "https://github.com/jamiesmith/astrophotography/tree/master/PySkyX/examples/"
    click ConfigExposure "https://github.com/jamiesmith/astrophotography/blob/master/PySkyX/per_filter_exposure_settings.csv"
    click ConfigFlatman "https://github.com/jamiesmith/astrophotography/blob/master/PySkyX/per_filter_flatman_settings.csv"
    click Documentation "https://github.com/jamiesmith/astrophotography/tree/master/PySkyX/documentation/"
    click OldScripts "https://github.com/jamiesmith/astrophotography/tree/master/PySkyX/old/"
    click AstroSummary "https://github.com/jamiesmith/astrophotography/blob/master/automation/astroImageSummary.sh"
    click ImportAstro "https://github.com/jamiesmith/astrophotography/blob/master/automation/importAstroPhotos.sh"
    click ImportDropbox "https://github.com/jamiesmith/astrophotography/blob/master/automation/importPhotosFromDropbox.sh"
    click ImportMirror "https://github.com/jamiesmith/astrophotography/blob/master/automation/importPhotosFromMirror.sh"
    click SyncPhotos "https://github.com/jamiesmith/astrophotography/blob/master/automation/syncPhotos.sh"
    click ShrinkJPEG "https://github.com/jamiesmith/astrophotography/blob/master/automation/shrinkJPEG.sh"
    click ParseBoltwood "https://github.com/jamiesmith/astrophotography/blob/master/automation/ParseBoltwood.awk"
    click Boltwood2CSV "https://github.com/jamiesmith/astrophotography/blob/master/automation/boltwood2csv.awk"
    click Boltwood2HTML "https://github.com/jamiesmith/astrophotography/blob/master/automation/boltwood2html.awk"
    click SummaryBoltwood "https://github.com/jamiesmith/astrophotography/blob/master/automation/summaryboltwood2csv.awk"
    click SummarizeImages "https://github.com/jamiesmith/astrophotography/blob/master/automation/summarizeAstroImages.sh"
    click EaglePS1 "https://github.com/jamiesmith/astrophotography/tree/master/automation/eagle/"
    click OpenFlipFlatBAT "https://github.com/jamiesmith/astrophotography/blob/master/automation/open-flip-flat.bat"
    click OpenFlipFlatCMD "https://github.com/jamiesmith/astrophotography/blob/master/automation/open-flip-flat.cmd"
    click CloseFlipFlatBAT "https://github.com/jamiesmith/astrophotography/blob/master/automation/close-flip-flat.bat"
    click CaptureFlatsJS "https://github.com/jamiesmith/astrophotography/blob/master/automation/theSkyX-JavaScript/CaptureFlats.js"
    click CommonUtilsJS "https://github.com/jamiesmith/astrophotography/blob/master/automation/theSkyX-JavaScript/CommonUtils.js"
    click FilterFocusOffsetsJS "https://github.com/jamiesmith/astrophotography/blob/master/automation/theSkyX-JavaScript/FilterFocusOffsets.js"
    click ImageRunTemplateJS "https://github.com/jamiesmith/astrophotography/blob/master/automation/theSkyX-JavaScript/ImageRunTemplate.js"
    click MessierMarathonJS "https://github.com/jamiesmith/astrophotography/blob/master/automation/theSkyX-JavaScript/MessierMarathon.js"
    click UnguidedDitherJS "https://github.com/jamiesmith/astrophotography/blob/master/automation/theSkyX-JavaScript/UnguidedDither.js"
    click UnguidedDitherHDRJS "https://github.com/jamiesmith/astrophotography/blob/master/automation/theSkyX-JavaScript/UnguidedDitherHDR.js"
    click AutoflatsJS "https://github.com/jamiesmith/astrophotography/blob/master/automation/theSkyX-JavaScript/autoflats.js"

    %% Styles
    classDef python fill:#D0E8FF,stroke:#026AA7,color:#000
    classDef automation fill:#E2F0D9,stroke:#2E7D32,color:#000
    classDef external fill:#FFF3CD,stroke:#FFB300,color:#000
    classDef datasource fill:#F0F0F0,stroke:#333,color:#000
```
