How zzilch/rplan-toolbox works
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.