# garthtb/lightness-curve architecture

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

- Interactive diagram: https://gitdiagram.com/garthtb/lightness-curve
- Repository: https://github.com/garthtb/lightness-curve

## Overview

##### Project Type and Purpose
- This is a standalone, cross-platform CLI image-analysis tool written in Rust.
- It ingests a directory (potentially ZIP archives) of images, computes per-frame brightness metrics (RGB avg, luminance, HSV channels, ROI), and emits CSV and/or SVG outputs.
- It is zero-dependency (static binary), high-throughput (parallel processing), config-driven, and automatable (no UI).

##### File Structure Analysis
- Top-level:
- Cargo.toml / Cargo.lock: Rust package manifest & lock file
- config/config.toml: default example configuration
- src/: source code broken into modules
- src/:
- main.rs – application entry: parse config, orchestrate pipeline
- config.rs – loads and validates config settings
- core.rs – pipeline control logic: file enumeration, parallel dispatch
- output_generator.rs – CSV writer and SVG-plot renderer
- This separation suggests a modular pipeline architecture:
Config loader → Core orchestrator → Image processing utilities → Output generator

##### Key Insights from README
- Parallel processing for performance
- Supports multiple image formats and metrics
- Driven entirely by config.toml
- Outputs CSV and SVG
- No interactive UI; pure CLI

##### Components
a. Configuration
– Component: “Config Loader”
– Input: config/config.toml or user-provided config.toml
b. Orchestration
– Component: “Core Pipeline”
– Responsibilities: scan directory, sort images, manage parallel tasks
c. Image Processing
– Component: “Image Utils Module”
– Responsibilities: decode image (JPEG, PNG, BMP, TIFF, WebP), extract ROI, compute metrics (RGB avg, Luminance, H/S/V)
d. Output Generation
– Component: “Output Generator”
– Responsibilities: aggregate results, write CSV, generate SVG line plot
e. External Interfaces
– File system (input images, output files)
– ZIP decompression (if applicable)
– Rust standard library and crates (e.g., image, rayon)
f. Execution Environment
– Single binary runs on host OS

##### Architectural Patterns & Principles
- Pipeline/Stage processing: clear stages from config to output
- Modularity: each src/*.rs is a self-contained module
- Parallelism: use of Rayon (or similar) to process images concurrently
- Single responsibility: strict separation of config, core logic, utilities, and output
- Zero runtime dependencies: static linking and minimal external crates

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Entry
    AppEntry["Application Entry\n(main.rs)"]:::config
    click AppEntry "https://github.com/garthtb/lightness-curve/blob/master/src/main.rs"

    %% Configuration
    DefaultConfig["Default Config File\n(config/config.toml)"]:::config
    click DefaultConfig "https://github.com/garthtb/lightness-curve/blob/master/config/config.toml"
    ConfigLoader["Config Loader"]:::config
    click ConfigLoader "https://github.com/garthtb/lightness-curve/blob/master/src/config.rs"

    %% Core Pipeline
    CorePipeline["Core Pipeline\n(orchestration, parallel dispatch)"]:::processing
    click CorePipeline "https://github.com/garthtb/lightness-curve/blob/master/src/core.rs"

    %% Image Utils Subgraph
    subgraph "Image Utils Module"
        direction TB
        ImageDecoder["Decoder\n(JPEG, PNG, BMP, TIFF, WebP)"]:::processing
        ROIExtractor["ROI Extractor\n(optional)"]:::processing
        MetricCalculator["Metric Calculator\n(RGB avg, Luminance, H/S/V)"]:::processing
    end
    click ImageUtils "https://github.com/garthtb/lightness-curve/blob/master/src/image_utils.rs"

    %% Output Generation
    OutputGenerator["Output Generator\n(CSV writer, SVG renderer)"]:::output
    click OutputGenerator "https://github.com/garthtb/lightness-curve/blob/master/src/output_generator.rs"

    %% External Systems
    FileSystem["File System"]:::external
    ZipHandler["ZIP Decompression"]:::external
    RustStd["Rust Std Library & Crates"]:::external
    RustManifest["Rust Package Manifest\n(Cargo.toml)"]:::external
    click RustManifest "https://github.com/garthtb/lightness-curve/blob/master/Cargo.toml"
    BinaryArtifact["Static Binary\n(Lightness-Curve)"]:::external

    %% Data Flow
    AppEntry -->|starts| ConfigLoader
    AppEntry -->|starts| CorePipeline

    DefaultConfig -->|config| ConfigLoader
    ConfigLoader -->|"configuration object"| CorePipeline

    CorePipeline -->|n workers| ImageDecoder
    ImageDecoder -->|image data| ROIExtractor
    ROIExtractor -->|ROI| MetricCalculator
    MetricCalculator -->|metrics| CorePipeline

    CorePipeline -->|collected metrics| OutputGenerator
    OutputGenerator -->|CSV/SVG files| FileSystem

    CorePipeline -->|reads images| FileSystem
    CorePipeline -->|unpacks ZIP| ZipHandler

    RustStd --> AppEntry
    RustStd --> ConfigLoader
    RustStd --> CorePipeline
    RustStd --> ImageDecoder
    RustStd --> OutputGenerator

    RustManifest -->|builds| BinaryArtifact

    %% Styles
    classDef config fill:#add8e6,stroke:#333,stroke-width:1px
    classDef processing fill:#90ee90,stroke:#333,stroke-width:1px
    classDef output fill:#ffa500,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
```
