# alexmeredith8299/opssat-cloud-detection architecture

> Architecture diagram of the GitHub repository alexmeredith8299/opssat-cloud-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexmeredith8299/opssat-cloud-detection
- Repository: https://github.com/alexmeredith8299/opssat-cloud-detection

## Overview

##### Project type and purpose
- This is an embedded image-processing experiment for a CubeSat (OPS-SAT).
- It integrates offline ML training (Python) with cross-compiled C/C++ algorithms to run on the satellite’s ARM-based processor.

##### File structure
- Top-level:
– CMakeLists.txt, Makefile, README.md, LICENSE
– src/ (main C++ algorithms)
– include/ (shared headers & constants)
– python/ (offline training & data-prep scripts)
– bin-arm/ & bin-sepp/ (cross-compile build pipelines & third-party libs)
– sandbox/, em_test/, release/ (testing outputs, deployment packaging)
- Patterns: layered build (third-party libs → core algorithms → packaging), clear separation of offline vs runtime code.

##### Extract README insights
- Four algorithms: luminosity threshold, random forest, U-Net, k-means.
- Build via CMake, deploy via shell scripts (e.g. random_forest.sh).
- Runs on ESA’s OPS-SAT with power/temperature telemetry.

##### Main components & their interactions
a. Development workstation
– Python environment
- lut_gen.py, tensorflow_dataloader.py, tf_train.ipynb → generate models or lookup tables.
– CMake build system
- Cross-compiler toolchain
- bin-arm/ (ARM pipeline) & bin-sepp/ (SEPP pipeline) drive downloads/builds of FP16, FXdiv, psimd, pthreadpool, abseil, eigen, xnnpack, flatbuffers, ruy, neon2sse, etc.
b. C++ Runtime modules
– src/main.cpp (luminosity, k-means, U-Net inference stub?)
– src/main_rf.cpp (random forest)
– Helper layer: include/constants.h, helper.h, stb_image*.h (I/O)
c. Deployment & execution
– Binaries (in bin-arm or release/)
– Shell scripts (random_forest.sh, start_exp185.sh, stop_exp185.sh)
– OPS-SAT Linux host (reads images → runs algorithms → logs outputs)
d. Data flow
– Input: raw satellite images (sandbox/io/… or camera feed)
– Processing: algorithm modules
– Output: masks, CSV logs, power/temperature metrics (em_test/, release/home/exp185/)

##### Architectural patterns & design principles
- Layered architecture:
– Third-party libraries (platform abstraction)
– Core image-processing algorithms (business logic)
– Deployment scripts and packaging (operational layer)
- Modular separation: Python‐only offline vs C++‐only onboard code.
- Cross-compile build pipeline isolates target‐specific dependencies.
- Clear boundaries: I/O → Processing → Reporting.

##### Detail level
– Show that the Python environment writes to a shared “models/” folder.
– Include the platform abstraction libraries (FP16, FXdiv, psimd, pthreadpool, xnnpack).
– Indicate configuration files (confu.yaml, config.dev.ini) feeding into the build/deploy scripts.

Conclusion

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Development Workstation
    subgraph "Development Workstation"
        direction TB
        Offline["Offline Training (Python)"]:::build
        CMakeBuild["Build Pipeline (Cross-compile)"]:::build
        Models["Models Folder"]:::data
    end

    %% Third-Party Libraries
    subgraph "Third-Party Libraries" 
        direction TB
        FP16["FP16-download"]:::tpl
        FXdiv["FXdiv-download"]:::tpl
        PSIMD["psimd-download"]:::tpl
        PTHREAD["pthreadpool-download"]:::tpl
        NEON2SSE["neon2sse"]:::tpl
        FLATBUF["flatbuffers"]:::tpl
        GEMMLOWP["gemmlowp"]:::tpl
        ABSEIL["abseil-cpp-populate-stamp"]:::tpl
        EIGEN["eigen-populate-stamp"]:::tpl
        XNNPACK["xnnpack-populate-stamp"]:::tpl
    end

    %% Core C++ Runtime
    subgraph "C++ Runtime (Onboard Inference)"
        direction TB
        Lum["Luminosity Threshold"]:::alg
        KMEANS["K-Means"]:::alg
        UNET["U-Net"]:::alg
        RF["Random Forest"]:::alg
        Helper["Helper Layer (I/O & Constants)"]:::alg
    end

    %% Deployment & Runtime
    subgraph "OPS-SAT Host"
        direction TB
        InputStorage["Sandboxed Images"]:::data
        CppRuntime["C++ Runtime"]:::alg
        OutputLogs["Test Outputs & Logs"]:::data
        Scripts["Deployment Scripts"]:::script
    end

    %% Packaging
    Release["Release Packaging"]:::build

    %% Connections
    Offline -->|"model export"| Models
    Models -->|"model files"| CMakeBuild
    CMakeBuild -->|"produces"| Binaries["Binaries"]:::build
    FP16 --> CMakeBuild
    FXdiv --> CMakeBuild
    PSIMD --> CMakeBuild
    PTHREAD --> CMakeBuild
    NEON2SSE --> CMakeBuild
    FLATBUF --> CMakeBuild
    GEMMLOWP --> CMakeBuild
    ABSEIL --> CMakeBuild
    EIGEN --> CMakeBuild
    XNNPACK --> CMakeBuild

    Binaries -->|"deployed to"| OPSHost["OPS-SAT Linux Host"]:::build
    OPSHost --> Scripts
    OPSHost --> InputStorage
    InputStorage --> CppRuntime
    CppRuntime --> Lum
    CppRuntime --> KMEANS
    CppRuntime --> UNET
    CppRuntime --> RF
    CppRuntime --> Helper
    CppRuntime -->|"inference output"| OutputLogs
    Scripts -->|"start/stop"| OPSHost
    Release --> Scripts
    Binaries --> Release

    %% Click Events
    click Offline "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/python/lut_gen.py"
    click Offline "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/python/tensorflow_dataloader.py"
    click Offline "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/python/tf_train.ipynb"
    click CMakeBuild "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/bin-arm/"
    click CMakeBuild "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/bin-sepp/"
    click FP16 "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/bin-arm/FP16-download/"
    click FXdiv "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/bin-arm/FXdiv-download/"
    click PSIMD "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/bin-arm/psimd-download/"
    click PTHREAD "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/bin-arm/pthreadpool-download/"
    click NEON2SSE "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/bin-arm/neon2sse/"
    click FLATBUF "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/bin-arm/flatbuffers/"
    click GEMMLOWP "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/bin-arm/gemmlowp/"
    click ABSEIL "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/bin-arm/src/abseil-cpp-populate-stamp/"
    click EIGEN "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/bin-arm/src/eigen-populate-stamp/"
    click XNNPACK "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/bin-arm/src/xnnpack-populate-stamp/"
    click Lum "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/src/main.cpp"
    click RF "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/src/main_rf.cpp"
    click Helper "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/include/constants.h"
    click Helper "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/include/stb_image.h"
    click Helper "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/include/stb_image_resize.h"
    click Helper "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/include/stb_image_write.h"
    click Scripts "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/random_forest.sh"
    click Scripts "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/release/home/exp185/start_exp185.sh"
    click Scripts "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/release/home/exp185/stop_exp185.sh"
    click InputStorage "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/sandbox/io/"
    click OutputLogs "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/em_test/"
    click Release "https://github.com/alexmeredith8299/opssat-cloud-detection/tree/main/release/"
    click Release "https://github.com/alexmeredith8299/opssat-cloud-detection/blob/main/release/home/exp185/config.dev.ini"

    %% Styles
    classDef build fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef alg fill:#90EE90,stroke:#333,stroke-width:1px
    classDef tpl fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef script fill:#f9c74f,stroke:#333,stroke-width:1px
```
