# yukistavailable/garmentimage architecture

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

- Interactive diagram: https://gitdiagram.com/yukistavailable/garmentimage
- Repository: https://github.com/yukistavailable/garmentimage

## Overview

##### Project Type and Purpose
- This is an open-source Python command-line tool (“GarmentImage”) for raster encoding and decoding of garment sewing patterns. It ingests JSON specifications of garment panels, applies geometric and mesh-based processing, then emits NumPy raster files (encode) or visualizations (decode).

##### File Structure Analysis
- Top level:
- assets/ – example JSON specs (.json) and reference NumPy files (.npy)
- encode.py, decode.py, main.py – CLI entrypoints
- pyproject.toml, uv.lock – build and environment lockfiles
- Core package: garmentimage/utils/
- decoder.py, encoder.py – high-level pipeline orchestrators
- mesh.py, template*.py, panel*.py, seam.py, face.py – domain models and geometric processing
- embedding.py, vertex2d.py, line2d.py, edge2d.py, utils2d.py – 2D geometry utilities
- neural_tailor_converter.py – optional conversion integration
- file.py – I/O for JSON and NumPy
- draw_panel.py – raster/PNG rendering

##### README Insights
- Uses UV for environment and task orchestration (uv run).
- Two main commands:
- python encode.py – JSON → .npy (with options for alignment, scaling)
- python decode.py – .npy → .png (visualization by garment_type)
- Emphasis on configurable encoding pipelines (darts, front/back alignment, etc.).

##### Diagramming the Architecture
a. Main Components
1. CLI Layer
– encode.py, decode.py, main.py
– UV runner as optional wrapper
2. I/O Module
– garmentimage/utils/file.py
– Reads JSON specs, writes/reads NumPy files, writes PNGs
3. Encoding Pipeline
– garmentimage/utils/encoder.py
– Domain modules: template, panel, seam, mesh, face, embedding
4. Decoding Pipeline
– garmentimage/utils/decoder.py
– Raster drawing: draw_panel.py
5. Geometry and Utility Libraries
– 2D primitives (vertex2d, line2d, edge2d), geometric helpers (utils2d)
6. External Environment
– UV task runner
– Python runtime, NumPy, external dependencies from pyproject.toml

b. Relationships & Data Flows
- I/O Module → Encoding Pipeline → NumPy output file
- NumPy file → I/O Module → Decoding Pipeline → Drawing Module → PNG output
- Geometry utilities feed into both encode and decode pipelines
- UV wraps CLI execution but is optional

c. Architectural Patterns & Principles
- Pipeline pattern: sequential processing stages (parse → mesh → encode/decode → render)
- Separation of concerns: I/O, core processing, and rendering modules are distinct
- Modular design for extensibility (e.g., neural_tailor_converter plug-in)
- Configuration via CLI flags instead of hardcoded parameters

d. Key Technologies & Frameworks
- Python 3.x, NumPy
- UV for reproducible environments and command orchestration
- JSON for input specs, PNG for visual output

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External / Environment"
        UV[UV Task Runner]:::external
        Python[Python Runtime & NumPy]:::external
    end

    subgraph "CLI Layer"
        Encode[encode.py]:::cli
        Decode[decode.py]:::cli
        Main[main.py]:::cli
    end

    subgraph "I/O Module"
        IO["file.py"]:::core
    end

    subgraph "Encoding Pipeline"
        Encoder["encoder.py"]:::core
    end

    subgraph "Decoding Pipeline"
        Decoder["decoder.py"]:::core
        Draw["draw_panel.py"]:::core
    end

    subgraph "Domain Models & Geometric Processing"
        Mesh["mesh.py"]:::domain
        Face["face.py"]:::domain
        Seam["seam.py"]:::domain
        Template["template.py"]:::domain
        TemplatePanel["template_panel.py"]:::domain
        Piece["piece.py"]:::domain
        Embedding["embedding.py"]:::domain
        Converter["neural_tailor_converter.py"]:::domain
    end

    subgraph "2D Geometry Utilities"
        V2["vertex2d.py"]:::util
        L2["line2d.py"]:::util
        E2["edge2d.py"]:::util
        U2["utils2d.py"]:::util
        U["utils.py"]:::util
    end

    subgraph "Reference Assets"
        JSON["assets/*.json"]:::assets
        NPY["assets/*.npy"]:::assets
    end

    UV -.-> Encode
    UV -.-> Decode
    Python --> Encoder
    Python --> Decoder

    Encode -->|"reads JSON"| IO
    IO -->|"spec JSON"| Encoder
    Encoder -->|"writes .npy"| IO
    IO --> NPY

    NPY --> IO
    IO -->|"loads .npy"| Decoder
    Decoder --> Draw
    Draw -->|"outputs PNG"| JSON

    Mesh --> Encoder
    Face --> Encoder
    Seam --> Encoder
    Template --> Encoder
    TemplatePanel --> Encoder
    Piece --> Encoder
    Embedding --> Encoder
    Converter --> Encoder

    V2 --> Encoder
    L2 --> Encoder
    E2 --> Encoder
    U2 --> Encoder
    U --> Encoder

    V2 --> Draw
    L2 --> Draw
    E2 --> Draw
    U2 --> Draw
    U --> Draw

    classDef cli fill:#6FA8DC,stroke:#333,stroke-width:1px;
    classDef core fill:#93C47D,stroke:#333,stroke-width:1px;
    classDef domain fill:#FFD966,stroke:#333,stroke-width:1px;
    classDef util fill:#F9CB9C,stroke:#333,stroke-width:1px;
    classDef external fill:#D9D9D9,stroke:#333,stroke-width:1px;
    classDef assets fill:#C27BA0,stroke:#333,stroke-width:1px;

    click Encode "https://github.com/yukistavailable/garmentimage/blob/main/encode.py"
    click Decode "https://github.com/yukistavailable/garmentimage/blob/main/decode.py"
    click Main "https://github.com/yukistavailable/garmentimage/blob/main/main.py"
    click IO "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/file.py"
    click Encoder "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/encoder.py"
    click Decoder "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/decoder.py"
    click Draw "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/draw_panel.py"
    click Mesh "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/mesh.py"
    click Face "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/face.py"
    click Seam "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/seam.py"
    click Template "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/template.py"
    click TemplatePanel "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/template_panel.py"
    click Piece "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/piece.py"
    click Embedding "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/embedding.py"
    click Converter "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/neural_tailor_converter.py"
    click V2 "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/vertex2d.py"
    click L2 "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/line2d.py"
    click E2 "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/edge2d.py"
    click U2 "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/utils2d.py"
    click U "https://github.com/yukistavailable/garmentimage/blob/main/garmentimage/utils/utils.py"
    click JSON "https://github.com/yukistavailable/garmentimage/tree/main/assets/"
    click NPY "https://github.com/yukistavailable/garmentimage/tree/main/assets/"
```
