# jamohile/stereoscopic-point-clouds architecture

> Architecture diagram of the GitHub repository jamohile/stereoscopic-point-clouds, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jamohile/stereoscopic-point-clouds
- Repository: https://github.com/jamohile/stereoscopic-point-clouds

## Overview

##### Project type and purpose
- This is a command-line, Python-based stereoscopic point-cloud generation tool.
- It ingests a pair of left/right 2D images, computes pixel disparities, triangulates a 3D point cloud, then post-processes it for smoothness.

##### File structure
- Top-level scripts each implement one pipeline stage:
- pre_process.py – any initial image preparation
- disparities.py – stereo matching & disparity map computation
- triangulation.py – converts disparities into 3D points
- post_process.py – smooths and fills the point cloud
- cloud_generation.py – orchestrates the full pipeline (if present) or serves utilities
- main.py – entry point that parses args, loads config, invokes pipeline
- utils.py – shared helper functions (I/O, logging, image ops)
- config.py – runtime parameters (camera baseline, window sizes, thresholds)
- static/ – documentation, sample images, and PDF theory guide

##### Readme insights
- Describes a four-stage pipeline: disparity estimation → triangulation → post-processing → visualization/export.
- Highlights use of stereo region matching, recursive smoothing, and Python3 execution.

##### Components
a. Main components
- Input Module: loads left/right images + camera parameters (config.py)
- Pre-processing Module: image normalization, grayscale conversion
- Disparity Estimation Module: region matching algorithm (disparities.py)
- Triangulation Module: depth calculation & point cloud generation (triangulation.py)
- Post-processing Module: smoothing, noise removal, hole filling (post_process.py)
- Output Module: writes or visualizes final point cloud (cloud_generation.py or main.py)
- Utility Layer: common functions (utils.py)
- Static Resources: sample data and documentation

b. Relationships & data flow

c. Architectural patterns & principles
- Pipeline/chain-of-responsibility – each stage consumes and produces data for the next
- Single responsibility per script for clarity and testability
- Config-driven parameters for algorithm tuning without code changes
- Modular utility layer to avoid duplication

d. Key technologies
- Python 3.x
- OpenCV or similar (implied by image operations)
- NumPy for array computations
- Custom stereo matching implementation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Point
    main["main.py\n(Entry Point)"]:::io

    %% Pipeline Stages
    pre["Pre-processing Module\n(pre_process.py)"]:::core
    disp["Disparity Estimation Module\n(disparities.py)"]:::core
    tri["Triangulation Module\n(triangulation.py)"]:::core
    post["Post-processing Module\n(post_process.py)"]:::post
    out["Output Module\n(cloud_generation.py)"]:::io

    %% Configuration and Utilities
    config["config.py\n(Parameters)"]:::util
    utils["utils.py\n(Utilities)"]:::util
    static["static/\nResources"]:::util

    %% Flow
    main --> pre
    pre --> disp
    disp --> tri
    tri --> post
    post --> out

    %% Config dependencies
    config -.-> pre
    config -.-> disp
    config -.-> tri
    config -.-> post
    config -.-> out

    %% Utils usage
    utils --> pre
    utils --> disp
    utils --> tri
    utils --> post
    utils --> out

    %% Static resources
    static

    %% Click Events
    click main "https://github.com/jamohile/stereoscopic-point-clouds/blob/master/main.py"
    click pre "https://github.com/jamohile/stereoscopic-point-clouds/blob/master/pre_process.py"
    click disp "https://github.com/jamohile/stereoscopic-point-clouds/blob/master/disparities.py"
    click tri "https://github.com/jamohile/stereoscopic-point-clouds/blob/master/triangulation.py"
    click post "https://github.com/jamohile/stereoscopic-point-clouds/blob/master/post_process.py"
    click out "https://github.com/jamohile/stereoscopic-point-clouds/blob/master/cloud_generation.py"
    click config "https://github.com/jamohile/stereoscopic-point-clouds/blob/master/config.py"
    click utils "https://github.com/jamohile/stereoscopic-point-clouds/blob/master/utils.py"
    click static "https://github.com/jamohile/stereoscopic-point-clouds/tree/master/static/"

    %% Styles
    classDef io fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef post fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
