# mzarowka/hsitools architecture

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

- Interactive diagram: https://gitdiagram.com/mzarowka/hsitools
- Repository: https://github.com/mzarowka/hsitools

## Overview

Based on our analysis of the file tree and README, the HSItools project is an R package designed for processing and visualizing hyperspectral core scanning data. It provides both a programmatic API and an interactive Shiny app interface for users to process raw hyperspectral images, extract spectral data, apply normalization and filtering operations, and finally generate visualizations (such as RGB composites).

##### Main Components
- User Interface (Shiny App):
- Represented by files like R/app.R and R/simpleShiny.R.
- This component handles interactive sessions and lets users set analysis parameters.
- Data Ingestion & Preprocessing:
- Functions in R/data.R, R/app_helpers.R, and related files handle reading raw hyperspectral data (evidenced by directories like inst/extdata and data-raw).
- Steps for preparing the core image (e.g., prepare_core()).
- Processing & Analysis Pipeline:
- Consists of modules for spectral extraction (R/extractors.R), spectral calculations (R/spectral_calculations.R), normalization (R/normalization.R), filtering (R/filters.R), and other processing tasks.
- These components form the core computation engine, transforming raw data to reflectance values and computed indices.
- Visualization & Output:
- Files like R/plotting.R and various plotting functions (e.g., plot_raster_rgb, plot_profile_spectral_profile.Rd) generate outputs.
- This component outputs final images, plots, and, in some cases, dataset exports.
- Documentation & Deployment:
- Documentation is detailed in the man folder (i.e., Rd files), vignettes, and the README.
- There are also CI/CD workflows using GitHub Actions (under .github/workflows) which indicate automated builds and checks.
- Utilities & Helper Modules:
- Other utility files under R/utils.R and workflow.R contain helper functions that support the main processing pipeline.

##### Relationships and Data Flow
- The data flows into the preprocessing module (prepare_core), and then through a series of processing functions (spectral calculations, filtering, normalization).
- Processed data is passed to visualization functions that generate output plots or files (RGB previews, reflectance images).
- Supporting helper functions and utilities streamline this data flow.
- A CI/CD pipeline oversees testing and package building, tying the codebase to deployment practices.

##### Architectural Patterns and Design Principles
- Modular Design: Clear separation of concerns is evident by splitting UI, processing, and visualization into distinct R scripts.
- Functional Pipeline: The project utilizes a functional programming style where data is passed through a series of transformation steps (e.g., core → prepare_core → stretch_raster_full → plot_raster_rgb).
- Extensibility and Reusability: The package’s structure (with numerous helper functions and clearly documented methods) facilitates easy extension for additional spectral processing methods.
- Integration with R-based tools: Leveraging R’s package ecosystem with CI/CD workflows (via GitHub Actions) and a Shiny interface demonstrates an integration of analysis and interactivity.

##### Technologies, Frameworks, and Libraries
- R Language: The core platform.
- Shiny: For creating the web-based interactive UI.
- Package Management: Integration with tools like pak for package installation.
- GitHub Actions: CI/CD for ongoing integration and checking (as indicated by YAML workflows).
- Other R libraries: Likely libraries for raster data handling and plotting (though not explicitly detailed, by function names they are likely used).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        UI1["Shiny App"] 
        UI2["Simple Shiny"]
    end

    %% Data Ingestion & Preprocessing Layer
    subgraph "Data Ingestion & Preprocessing"
        D_C1["Raw Data: data-raw"]
        D_C2["Raw Data: inst/extdata"]
        D_A["Data Functions"]
        D_B["App Helpers"]
    end

    %% Processing & Analysis Pipeline
    subgraph "Processing & Analysis Pipeline"
        P1["Extractors"]
        P2["Spectral Calculations"]
        P3["Normalization"]
        P4["Filters"]
    end

    %% Visualization & Output
    subgraph "Visualization & Output"
        V1["Plotting"]
        V2["RGB Composite"]
    end

    %% Utilities & Helper Modules
    subgraph "Utilities & Helper Modules"
        U1["Utilities"]
        U2["Workflow"]
    end

    %% Documentation & Deployment
    subgraph "Documentation & Deployment"
        D_doc1["Documentation (man)"]
        D_doc2["Vignettes"]
        D_doc3["README"]
        D_doc4["CI/CD & Workflows"]
    end

    %% Connections for main data flow
    UI1 -->|"triggers"| D_A
    UI2 -->|"triggers"| D_A

    D_C1 -->|"provides data"| D_A
    D_C2 -->|"provides data"| D_A
    D_A -->|"preprocesses"| P1
    D_B -->|"assists"| P1

    P1 -->|"processes"| P2
    P2 -->|"processes"| P3
    P3 -->|"processes"| P4
    P4 -->|"feeds"| V1
    V1 -->|"renders"| V2

    %% Utilities support processing
    U1 -.->|"supports"| P1
    U2 -.->|"supports"| P1

    %% Documentation & Deployment support overall project
    D_doc3 -.->|"supports"| UI1
    D_doc1 -.->|"supports"| D_A
    D_doc4 -.->|"supports"| P1
    D_doc2 -.->|"supports"| V1

    %% Click Events for User Interface
    click UI1 "https://github.com/mzarowka/hsitools/blob/main/R/app.R"
    click UI2 "https://github.com/mzarowka/hsitools/blob/main/R/simpleShiny.R"

    %% Click Events for Data Ingestion & Preprocessing
    click D_A "https://github.com/mzarowka/hsitools/blob/main/R/data.R"
    click D_B "https://github.com/mzarowka/hsitools/blob/main/R/app_helpers.R"
    click D_C1 "https://github.com/mzarowka/hsitools/tree/main/data-raw"
    click D_C2 "https://github.com/mzarowka/hsitools/tree/main/inst/extdata"

    %% Click Events for Processing & Analysis Pipeline
    click P1 "https://github.com/mzarowka/hsitools/blob/main/R/extractors.R"
    click P2 "https://github.com/mzarowka/hsitools/blob/main/R/spectral_calculations.R"
    click P3 "https://github.com/mzarowka/hsitools/blob/main/R/normalization.R"
    click P4 "https://github.com/mzarowka/hsitools/blob/main/R/filters.R"

    %% Click Events for Visualization & Output
    click V1 "https://github.com/mzarowka/hsitools/blob/main/R/plotting.R"
    click V2 "https://github.com/mzarowka/hsitools/blob/main/man/plot_raster_rgb.Rd"

    %% Click Events for Utilities & Helper Modules
    click U1 "https://github.com/mzarowka/hsitools/blob/main/R/utils.R"
    click U2 "https://github.com/mzarowka/hsitools/blob/main/R/workflow.R"

    %% Click Events for Documentation & Deployment
    click D_doc1 "https://github.com/mzarowka/hsitools/tree/main/man"
    click D_doc2 "https://github.com/mzarowka/hsitools/tree/main/vignettes"
    click D_doc3 "https://github.com/mzarowka/hsitools/blob/main/README.Rmd"
    click D_doc4 "https://github.com/mzarowka/hsitools/tree/main/.github/workflows"

    %% Styles
    classDef ui fill:#AADDFF,stroke:#333,stroke-width:2px;
    classDef data fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef proc fill:#FFDD88,stroke:#333,stroke-width:2px;
    classDef vis fill:#FFBBBB,stroke:#333,stroke-width:2px;
    classDef util fill:#DDAAFF,stroke:#333,stroke-width:2px;
    classDef docs fill:#FFFFAA,stroke:#333,stroke-width:2px;

    %% Assign classes to nodes
    class UI1,UI2 ui;
    class D_A,D_B,D_C1,D_C2 data;
    class P1,P2,P3,P4 proc;
    class V1,V2 vis;
    class U1,U2 util;
    class D_doc1,D_doc2,D_doc3,D_doc4 docs;
```
