# elerac/polanalyser architecture

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

- Interactive diagram: https://gitdiagram.com/elerac/polanalyser
- Repository: https://github.com/elerac/polanalyser

## Overview

##### Project type and purpose
- Polanalyser is an open-source Python library/tool for polarization image analysis.

##### File structure
- Top-level:
- LICENSE, README.md, setup.py
- documents/ (scripts to build docs/assets, notation definitions, static images)
- examples/ (client scripts demonstrating library usage)
- polanalyser/ (the package)
- polanalyser/ sub-packages and modules:
- __init__.py (public API)
- container.py (data containers)
- demosaicing.py
- stokes.py
- mueller.py
- visualization.py
- io/ (image_io.py, json_io.py, README.md)
- sympy/ (symbolic versions using SymPy)

##### README for insights
- Describes four main feature areas:
a. Demosaicing
b. Stokes vector analysis
c. Mueller matrix analysis
d. Visualization (numeric & symbolic)
- Lists dependencies: NumPy, OpenCV, matplotlib, SymPy (optional).

##### Components & Interactions
1. Client / Example Scripts
2. polanalyser API Layer (polanalyser/__init__.py)
3. IO Subsystem (polanalyser/io/image_io.py, json_io.py)
4. Core Computation Modules:
– Demosaicing
– Stokes Calculation
– Mueller Calculation
5. Visualization Module
6. Symbolic Computation Layer (polanalyser/sympy)
7. External Dependencies (NumPy, OpenCV, matplotlib, SymPy)
8. File System / Dataset Storage

- Client → API Layer (e.g., calls pa.demosaicing())
- API Layer → IO Subsystem (loads raw images/metadata)
- IO → Core Computation Modules (passes arrays/matrices)
- Core Modules ↔ External Libraries (NumPy operations, cv2)
- Visualization → File System or Display
- API Layer → Symbolic Module (if user calls symbolic API)
- Symbolic Module ↔ SymPy

c. Architectural patterns & principles:
- Layered architecture (Presentation → API → IO → Core → Visualization)
- Modular design: each optical computation in its own module
- Optional extension (SymPy) without polluting core
- Clear separation of concerns for maintainability

d. Key technologies/frameworks:
- Python 3.x
- NumPy (numerical computing)
- OpenCV (image I/O, processing)
- Matplotlib (plotting, colormaps)
- SymPy (symbolic algebra)
- setuptools / setup.py (packaging)

##### Detail level checklist
- Sub-packages under polanalyser: demosaicing, stokes, mueller, io, visualization, sympy.
- Interactions with external libs (NumPy, OpenCV, matplotlib, SymPy).
- Example scripts as clients invoking the API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Client["Client / Examples"]:::client
    end

    subgraph "API Layer"
        API["polanalyser/__init__.py"]:::api
    end

    subgraph "IO Subsystem"
        IO_pkg["polanalyser/io"]:::io
        ImgIO["image_io.py"]:::io
        JsonIO["json_io.py"]:::io
        IO_pkg --> ImgIO
        IO_pkg --> JsonIO
    end

    subgraph "Core Computation"
        Container["container.py"]:::core
        Demosaic["demosaicing.py"]:::core
        Stokes["stokes.py"]:::core
        Mueller["mueller.py"]:::core
    end

    subgraph "Visualization Module"
        Viz["visualization.py"]:::viz
    end

    subgraph "Symbolic Computation (optional)"
        SympPkg["polanalyser/sympy"]:::sympy
        SymStokes["stokes.py"]:::sympy
        SymMueller["mueller.py"]:::sympy
        SympPkg --> SymStokes
        SympPkg --> SymMueller
    end

    subgraph "External Libraries"
        NumPy["NumPy"]:::external
        OpenCV["OpenCV"]:::external
        Matplotlib["Matplotlib"]:::external
        SymPy["SymPy"]:::external
    end

    Storage["File System / Datasets"]:::storage

    subgraph "Docs & Config"
        Docs["documents/"]:::docs
        Setup["setup.py"]:::docs
        License["LICENSE"]:::docs
        Readme["README.md"]:::docs
    end

    %% Data Flow
    Client -->|"import pa"| API
    API -->|"load images"| IO_pkg
    IO_pkg --> Storage
    IO_pkg --> Container
    Container --> Demosaic
    Container --> Stokes
    Container --> Mueller
    API -->|"pa.demosaicing()"| Demosaic
    API -->|"calcStokes()"| Stokes
    API -->|"calcMueller()"| Mueller
    API -->|"pa.visualization()"| Viz
    API -->|"symbolic API"| SympPkg
    IO_pkg --> Demosaic
    IO_pkg --> Stokes
    IO_pkg --> Mueller

    Demosaic --> NumPy
    Demosaic --> OpenCV
    Stokes --> NumPy
    Mueller --> NumPy
    Viz --> Matplotlib
    SymStokes --> SymPy
    SymMueller --> SymPy
    Viz -->|"output images"| Storage

    %% Click Events
    click Client "https://github.com/elerac/polanalyser/tree/main/examples/"
    click API "https://github.com/elerac/polanalyser/blob/main/polanalyser/__init__.py"
    click IO_pkg "https://github.com/elerac/polanalyser/blob/main/polanalyser/io/__init__.py"
    click ImgIO "https://github.com/elerac/polanalyser/blob/main/polanalyser/io/image_io.py"
    click JsonIO "https://github.com/elerac/polanalyser/blob/main/polanalyser/io/json_io.py"
    click Demosaic "https://github.com/elerac/polanalyser/blob/main/polanalyser/demosaicing.py"
    click Stokes "https://github.com/elerac/polanalyser/blob/main/polanalyser/stokes.py"
    click Mueller "https://github.com/elerac/polanalyser/blob/main/polanalyser/mueller.py"
    click Container "https://github.com/elerac/polanalyser/blob/main/polanalyser/container.py"
    click Viz "https://github.com/elerac/polanalyser/blob/main/polanalyser/visualization.py"
    click SympPkg "https://github.com/elerac/polanalyser/blob/main/polanalyser/sympy/__init__.py"
    click SymStokes "https://github.com/elerac/polanalyser/blob/main/polanalyser/sympy/stokes.py"
    click SymMueller "https://github.com/elerac/polanalyser/blob/main/polanalyser/sympy/mueller.py"
    click Docs "https://github.com/elerac/polanalyser/tree/main/documents/"
    click Setup "https://github.com/elerac/polanalyser/blob/main/setup.py"
    click License "https://github.com/elerac/polanalyser/tree/main/LICENSE"
    click Readme "https://github.com/elerac/polanalyser/blob/main/README.md"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef api fill:#D0F0E0,stroke:#22863a,color:#22863a;
    classDef io fill:#E6F4EA,stroke:#22863a,color:#22863a;
    classDef core fill:#FFEFD5,stroke:#d18600,color:#d18600;
    classDef viz fill:#F3E5FF,stroke:#6f42c1,color:#6f42c1;
    classDef sympy fill:#FFE6E6,stroke:#d73a49,color:#d73a49,stroke-dasharray:5 5;
    classDef external fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
    classDef storage fill:#FFF5B1,stroke:#735C0F,color:#735C0F;
    classDef docs fill:#FFFBEB,stroke:#735C0F,color:#735C0F;
```
