# bchao1/homography architecture

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

- Interactive diagram: https://gitdiagram.com/bchao1/homography
- Repository: https://github.com/bchao1/homography

## Overview

##### Project Type and Purpose
- This is a command-line image‐processing tool (a Python “homography” utility) that reads a background canvas and one or more source images, computes a projective transform (homography) for each source, warps them onto the canvas, and writes out a composite image.

##### File Structure Analysis
- Top level
– README.md, ref.md, data/, images/, results/
- Main module (homography/)
– config.yaml          ← user parameters (paths & target corner coordinates)
– main.py              ← entry point, parses config, orchestrates pipeline
– util/
- get_corner.py    ← helper to retrieve corner coordinates from source images
- poly_edit.py     ← polygon manipulation or visualization utilities
- “data/” holds sample images; “results/” holds output; “images/” holds documentation figures.

##### Key Points from README
- Usage: ‘python3 main.py’ in homography/
- Config-driven: canvas_image, project_images[], output_image, coors[]
- Algorithm: build matrix A from four corner correspondences, solve Ah=0 via SVD, apply H to warp the image, composite onto canvas.

a. Main Components
1. CLI & Config Loader
- Reads homography/config.yaml
- Validates parameters
2. File System & I/O
- Input folders: data/, user-supplied images
- Output folder: results/
3. Core Pipeline (homography/main.py)
- For each project_image:
– get_corner (util)
– Build correspondence matrix A (internal routine)
– SVD solver (numpy / scipy) → H matrix
– Warp routine (OpenCV or numpy) → transformed image
– Composite onto canvas
4. Utility Modules
- homography/util/get_corner.py
- homography/util/poly_edit.py
5. External Libraries
- PyYAML → parse config.yaml
- NumPy / SciPy → linear algebra, SVD
- OpenCV (cv2) or PIL → image load/warp/composite
b. Relationships & Data Flow
- User → CLI → Config Loader
- Config → main pipeline
- main.py reads canvas_image & project_images → File I/O
- get_corner & poly_edit utilities feed into homography solver
- Solver outputs warped images → composite step
- Composite → write output_image → File I/O → results/
c. Architectural Patterns & Principles
- Modular design: separation between orchestration (main.py), configuration, utilities, and external libraries
- Data-driven: behavior entirely controlled by config.yaml
- Single responsibility: each util module handles a specific subtask
d. Technologies / Frameworks
- Python 3.x
- PyYAML
- NumPy / SciPy
- OpenCV or PIL/Pillow

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Inputs"
        Config["Config Loader\n(homography/config.yaml)"]:::input
        DataDir["Input Data\ndata/"]:::input
        ImagesDir["Documentation Images\nimages/"]:::input
        Documentation["Project Docs\n(README.md, ref.md)"]:::input
    end

    subgraph "Core Pipeline"
        Main["Main Orchestrator\n(homography/main.py)"]:::core
        subgraph "Utilities"
            Corner["Corner Extraction Utility\n(homography/util/get_corner.py)"]:::util
            Poly["Polygon Manipulation Utility\n(homography/util/poly_edit.py)"]:::util
        end
        Solver["Homography Solver\n(SVD via NumPy/SciPy)"]:::core
        Warper["Image Warper\n(OpenCV/PIL)"]:::core
        Composite["Composite Module\n(canvas + warped)"]:::core
    end

    subgraph "External Libraries"
        PyYAML["PyYAML"]:::ext
        NumPy["NumPy/SciPy"]:::ext
        CV["OpenCV/PIL"]:::ext
    end

    Output["Output Results\n(results/)"]:::output

    %% Data Flow
    Config -->|"config dict"| Main
    DataDir -->|"source images"| Main
    Documentation -->|"usage docs"| Main

    Main -->|"retrieve corners"| Corner
    Corner -->|"corner coords"| Main
    Main -->|"build matrix A"| Solver
    Solver -->|"H matrix"| Warper
    Warper -->|"warped image"| Composite
    Config -->|"canvas path"| Composite
    Composite -->|"composite image"| Output

    %% External Library Dependencies
    Main --> PyYAML
    Solver --> NumPy
    Warper --> CV

    %% Click Events
    click Main "https://github.com/bchao1/homography/blob/master/homography/main.py"
    click Config "https://github.com/bchao1/homography/blob/master/homography/config.yaml"
    click Corner "https://github.com/bchao1/homography/blob/master/homography/util/get_corner.py"
    click Poly "https://github.com/bchao1/homography/blob/master/homography/util/poly_edit.py"
    click DataDir "https://github.com/bchao1/homography/tree/master/data/"
    click ImagesDir "https://github.com/bchao1/homography/tree/master/images/"
    click Output "https://github.com/bchao1/homography/tree/master/results/"
    click Documentation "https://github.com/bchao1/homography/blob/master/README.md"

    %% Styles
    classDef input fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef util fill:#bfb,stroke:#333,stroke-width:1px
    classDef ext fill:#ffb,stroke:#333,stroke-width:1px
    classDef output fill:#fbf,stroke:#333,stroke-width:1px
```
