# zzilch/rplan-toolbox architecture

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

- Interactive diagram: https://gitdiagram.com/zzilch/rplan-toolbox
- Repository: https://github.com/zzilch/rplan-toolbox

## Overview

##### Project type and purpose
- This is an open-source Python/Matlab toolbox for processing and analyzing the RPLAN floorplan dataset.
- It provides CLI scripts, a Python API (`rplan/` package), and uses Matlab Engine for certain alignment routines.

A. Entry points (CLI scripts & test harnesss)
– batch_*.py (e.g. batch_align.py, batch_box2img.py, …)
– cluster_tf.py
– test.py
B. Core Python library (`rplan/` package)
1. floorplan.py
- Floorplan class: loads PNG image, exposes four channels (`boundary`, `category`, `instance`, `inside`), and `to_dict()` for vector data
2. align.py
- `align_fp_gt()` wraps both pure-Python routines and calls out to Matlab Engine for boundary/neighbor alignment
3. decorate.py
- `get_dw()` to add doors/windows to a vector floorplan
4. measure.py
- `compute_tf()` computes the turning function
- `TFRetriever` class for KNN and brute-force retrieval
5. plot.py
- Plotting utilities: `plot_boundary`, `plot_graph`, `plot_fp`, `plot_tf`, etc.
6. utils.py
- Shared helpers (I/O, vector ↔ array conversions)
C. External/third-party services
– Matlab Engine API (for advanced alignment algorithms in `rplan/matlab/`)
– FAISS (for clustering in `cluster_tf.py`)
D. Data stores
– `data/` directory (raw input PNGs)
– `output/` directory (plots, TF arrays, centroids, clusters)

##### Relationships and data flow
1. User picks a script (e.g. `batch_align.py`)
2. Script invokes Floorplan class → loads `data/*.png`
3. Floorplan produces raw image channels + vector dict
5. `decorate.py` inserts doors/windows
6. `measure.py` computes turning function → optionally feed into `cluster_tf.py` (requires FAISS)
7. `plot.py` visualizes any or all intermediate results → writes to `output/`
8. `TFRetriever` may be used standalone to retrieve similar floorplans by turning function

##### Architectural patterns & design principles
- Modular design: each subpackage (`align`, `decorate`, `measure`, `plot`) has a single responsibility.
- CLI-to-API separation: scripts import and orchestrate library functions—no logic duplication.
- External-engine integration: Matlab routines are kept under `rplan/matlab/` and invoked via Matlab Engine API.
- Data-flow pipeline: raw data → vector extraction → alignment → decoration → measurement → clustering/retrieval → plotting.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Entry Points"
        BA_ALIGN["batch_align.py"]:::entry
        BA_BOX2["batch_box2img.py"]:::entry
        BA_DEC["batch_decorate.py"]:::entry
        BA_SAVE["batch_save.py"]:::entry
        BA_TF["batch_tf.py"]:::entry
        CLUSTER["cluster_tf.py"]:::entry
        TEST["test.py"]:::entry
    end

    subgraph "Core Python Library"
        FPLAN["rplan/floorplan.py\nFloorplan"]:::core
        ALIGN["rplan/align.py\nalign_fp_gt()"]:::core
        DEC["rplan/decorate.py\nget_dw()"]:::core
        MEAS["rplan/measure.py\ncompute_tf()\nTFRetriever"]:::core
        PLOT["rplan/plot.py\nplot utilities"]:::core
        UTIL["rplan/utils.py"]:::core
    end

    subgraph "External Dependencies"
        MATLAB["rplan/matlab/\nMatlab Engine API"]:::external
        FAISS["FAISS Library"]:::external
    end

    subgraph "Data Stores"
        RAW["data/"]:::data
        OUT["output/"]:::data
    end

    BA_ALIGN -->|".png images"| FPLAN
    BA_BOX2 -->|".png images"| FPLAN
    BA_DEC -->|".png images"| FPLAN
    BA_SAVE -->|".png images"| FPLAN
    BA_TF -->|".png images"| FPLAN
    TEST -->|".png images"| FPLAN

    FPLAN -->|"vector dict"| ALIGN
    ALIGN -->|"aligned dict"| DEC
    DEC -->|"decorated dict"| MEAS
    MEAS -->|"TF array"| PLOT
    PLOT -->|"plots"| OUT

    MEAS -->|"TF arrays"| CLUSTER
    CLUSTER -->|"clusters, centroids"| OUT

    ALIGN -->|"calls"| MATLAB
    CLUSTER -->|"uses"| FAISS

    UTIL --> FPLAN
    UTIL --> ALIGN
    UTIL --> DEC
    UTIL --> MEAS
    UTIL --> PLOT

    click BA_ALIGN "https://github.com/zzilch/rplan-toolbox/blob/master/batch_align.py"
    click BA_BOX2 "https://github.com/zzilch/rplan-toolbox/blob/master/batch_box2img.py"
    click BA_DEC "https://github.com/zzilch/rplan-toolbox/blob/master/batch_decorate.py"
    click BA_SAVE "https://github.com/zzilch/rplan-toolbox/blob/master/batch_save.py"
    click BA_TF "https://github.com/zzilch/rplan-toolbox/blob/master/batch_tf.py"
    click CLUSTER "https://github.com/zzilch/rplan-toolbox/blob/master/cluster_tf.py"
    click TEST "https://github.com/zzilch/rplan-toolbox/blob/master/test.py"
    click FPLAN "https://github.com/zzilch/rplan-toolbox/blob/master/rplan/floorplan.py"
    click ALIGN "https://github.com/zzilch/rplan-toolbox/blob/master/rplan/align.py"
    click DEC "https://github.com/zzilch/rplan-toolbox/blob/master/rplan/decorate.py"
    click MEAS "https://github.com/zzilch/rplan-toolbox/blob/master/rplan/measure.py"
    click PLOT "https://github.com/zzilch/rplan-toolbox/blob/master/rplan/plot.py"
    click UTIL "https://github.com/zzilch/rplan-toolbox/blob/master/rplan/utils.py"
    click MATLAB "https://github.com/zzilch/rplan-toolbox/tree/master/rplan/matlab/"

    classDef entry fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6cf,stroke:#333,stroke-width:1px
    classDef external fill:#f96,stroke:#333,stroke-width:1px
    classDef data fill:#aaa,stroke:#333,stroke-width:1px
```
