Metadata-Version: 2.4
Name: cuger
Version: 0.1.0
Summary: Convex graph encoding and representation toolkit for building geometry
Author: CUGER contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Romeo_Leeyh/CUGER_building
Project-URL: Repository, https://github.com/Romeo_Leeyh/CUGER_building
Keywords: building,geometry,graph,bim,bem
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: networkx>=2.6.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: pygeos>=0.10.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: seaborn>=0.11.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Dynamic: license-file

# CUGER_building

## Introduction

**CUGER** is a Python-based open-source representation tool that decomposes complex building shapes/plans into convex geometry **and encodes them into an improved LPG (Logical Property Graph) structure**.  
It further supports **bidirectional conversion between LPG and RDF**, enabling seamless interoperability across heterogeneous building data ecosystems. 🔄

CUGER is not only designed for **converting design models into engineering-level BIM/BEM structures**, but also for **transforming building models into graph datasets for GNN training**—supporting downstream tasks such as performance prediction, spatial reasoning, and surrogate simulation. 🧠📐

Conceptually, the framework draws inspiration from **Arkin, Ronald C. (1987)**, *“Path Planning for a Vision-Based Autonomous Robot.”*

CUGER is built on top of **Moosas**, and to access its full functionality—including building-model conversion, geometric/semantic recognition, and structured graph generation—you need to install both **CUGER** and **Moosas**.  
The algorithm is also integrated into **Moosas+**, and its implementation can be found in: 👉 [`moosas/MoosasPy/encoding`](https://github.com/UmikoXiao/moosas)

### New: Simplify (LOD) Module

CUGER now includes a **geometry simplification stage** before convex decomposition.

- `precise`: keep original geometry (no simplification)
- `medium`: simplify to **multi-layer OBB** representation
- `low`: simplify to **single OBB** representation

This feature is integrated in the processing pipeline as:

`Simplify (LOD) -> Convexify -> (optional) Moosas export -> (optional) Graph generation`

## Installation

### Install from PyPI

```bash
pip install cuger
```

The core package only contains the code under `cuger/cuger`.
If you also need Moosas-based export (`.geo/.xml/.idf/.owl`) and graph generation,
please install Moosas separately.

### Install from git

```bash
git clone https://github.com/Romeo_Leeyh/CUGER_building.git
cd cuger
pip install -e .

# or install requirements directly
pip install -r requirements.txt 
```

### Install Moosas+

If you just want to try the algorithm to split building models, this step can be ignored. For full installation instructions, please visit the Moosas+ [repository](https://github.com/UmikoXiao/moosas).

## Usage

### Run with Test Script

You can run the example script in `test.py`.  
This will process sample building models under `tests/examples/`  
and generate outputs in `tests/example_results/`.

```cmd
tests
├── examples
│   └── example0.geo        # Sample test case
└── example_results
    ├── geo_s               # Simplified geometry (_s_<lod>.geo)
    ├── figure_convex       # Convex decomposition figures
    ├── figure_graph        # Graph visualization figures
    ├── geo_c               # Convex converted geometric files
    ├── graph               # Generated graph nodes and edges
    ├── new_geo             # Exported .geo files
    ├── new_idf             # Exported .idf files
    ├── new_rdf             # Exported .rdf files
    └── new_xml             # Exported .xml files
```

To run the test:

```bash
python test.py
```

### Use as a Python package

The public API follows the same main flow used in `test.py`:

```python
from cuger import PipelineOptions, process_geo_directory, process_geo_file

options = PipelineOptions(lod="medium")

process_geo_file("tests/examples/example0.geo", "tests/example_results", options=options)

process_geo_directory("tests/examples", "tests/example_results", options=options)
```

If you only want simplification + convex decomposition and do not want to depend on Moosas:

```python
from cuger import PipelineOptions, process_geo_file

options = PipelineOptions(
  lod="medium",
  run_moosas=False,
  generate_graph=False,
)

process_geo_file("tests/examples/example0.geo", "tests/example_results", options=options)
```

### CLI

After installation, you can also use the packaged command:

```bash
cuger -s tests/examples/example0.geo -o tests/example_results -l medium
cuger -i tests/examples -o tests/example_results -l medium
```

### Publish to PyPI

Before publishing, update the version in `pyproject.toml`.

Build the package:

```bash
python -m pip install -U build twine
python -m build
```

This generates:

- `dist/cuger-<version>.tar.gz`
- `dist/cuger-<version>-py3-none-any.whl`

Validate the distribution metadata locally:

```bash
python -m twine check dist/*
```

Upload to **TestPyPI** first:

```bash
python -m twine upload --repository testpypi dist/*
```

Then test installation:

```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple cuger
```

If everything looks good, upload to the official **PyPI** index:

```bash
python -m twine upload dist/*
```

After release, verify installation from PyPI:

```bash
pip install -U cuger
```

Optional: configure credentials with `.pypirc` or environment variables such as
`TWINE_USERNAME` and `TWINE_PASSWORD` to avoid typing them each time.

### GitHub Actions Auto Publish (PyPI)

This repository includes CI workflow: `.github/workflows/publish-pypi.yml`.

- Push tag `v*` (for example `v0.1.1`) -> build and publish to **PyPI**
- Manual run (`workflow_dispatch`) -> choose **testpypi** or **pypi**

#### One-time configuration (Trusted Publisher)

- In PyPI project settings (`cuger`), add a **Trusted Publisher**.
- Owner: your GitHub org/user.
- Repository: `cuger` repository.
- Workflow name: `publish-pypi.yml`.
- Environment: `pypi`.

- In TestPyPI project settings (`cuger`), add another Trusted Publisher.
- Use the same repository and workflow.
- Environment: `testpypi`.

- In GitHub repository settings, create environments: `pypi` and `testpypi`.

No PyPI API token secret is required when using Trusted Publisher (OIDC).

#### Release commands

```bash
# 1) bump version in pyproject.toml
# 2) commit and push
git tag v0.1.1
git push origin v0.1.1
```

If you want to dry-run to TestPyPI first, use **Actions -> Publish Python Package -> Run workflow -> repository=testpypi**.

### Run with CLI (`main.py`)

`main.py` supports interactive mode and command-line mode.

```bash
# interactive mode
python main.py

# batch process a directory
python main.py -i tests/examples -o tests/example_results -l medium

# process a single file
python main.py -s tests/examples/example0.geo -o tests/example_results -l low
```

LOD options:

- `precise` (default copy/no simplify in simplify stage)
- `medium` (recommended)
- `low`

### Module I/O Explanation

CUGER operates through a series of processing modules. Each module consumes specific input files and produces standardized outputs that together form the unified graph-based representation of the building model.

#### **Input**

- **`.geo` file**  
  The primary geometric description of the building.  
  This file contains surfaces, edges, vertex positions, and semantic tags used to reconstruct the building’s spatial structure.

#### **Intermediate Outputs**

- **`geo_s/<case_name>_s_<lod>.geo`**  
  Simplified geometry generated by the new **simplify** stage.
  - `lod=precise`: copied from input geometry
  - `lod=medium`: multi-layer OBB simplified geometry
  - `lod=low`: single OBB simplified geometry

- **`figure_convex/<case_name>_convex.png`**  
  Visualization of the convex decomposition process, showing how non-convex polygons are split.
- **`figure_graph/<case_name>_graph.png`**  
  Graph-level visualizations illustrating nodes, edges, and spatial relationships.
- **`geo_c/<case_name>_c.geo`**  
  Converted or cleaned geometric files after preprocessing and convex decomposition.

#### **Graph Outputs**


- **`graph/<case_name>.json`**  
  Encodes all nodes (faces, spaces, openings, etc.) with geometric, semantic, and topological attributes.
  
  Encodes adjacency relations, directional edges, and multi-scale topology for downstream GNN tasks.

<div style="display: flex; gap: 0pt;">
  <img src="tests/example_results/figure_convex/example0_convex.png" 
       style="height: 250pt; object-fit: cover; clip-path: inset(10% 15% 10% 15%);">

  <img src="tests/example_results/figure_graph/example0_graph.png" 
       style="height: 250pt; object-fit: cover; clip-path: inset(10% 15% 10% 15%);">
</div>

#### **Exported Model Formats**

- **`new_geo/<case_name>.geo`**  
  Reconstructed geometry exported back into `.geo` format.
- **`new_idf/<case_name>.idf`** *(in development)*  
  Prototype EnergyPlus IDF export based on the generated graph structure.
- **`new_rdf/<case_name>.owl`**  
  Semantic web representation exported as RDF, suitable for linked-data workflows, which is dumped in `.owl` format.
- **`new_xml/<case_name>.xml`**  
  XML-based representation for interoperability with external BIM or simulation environments.

#### **Processing Stages**

1. **Simplify (`simplify_process`)**  
  Input `.geo` -> simplified `.geo` in `geo_s/` according to selected LOD.
2. **Convexify (`convex_process`)**  
  Simplified `.geo` -> convex `.geo` in `geo_c/`.
3. **Model Export (Moosas, optional)**  
  Convex `.geo` -> `.geo/.xml/.owl/.idf` exports.
4. **Graph Construction (`graph_process`, optional)**  
  Build LPG JSON graph and visualization figures.

## Function

Core entry points:

- `main.py` (CLI + interactive processing)
- `test.py` (example pipeline run)
- `cuger/__transform/process.py`
  - `simplify_process(...)`
  - `convex_process(...)`
  - `graph_process(...)`

## Citation

If you used this project in your research, please cite the paper below:

```bibtex
@article{liGeometryGraphAutomation2026,
  title = {From Geometry to Graph: {{Automation}} of Building Performance Modeling via Convex Graph Encoding},
  shorttitle = {From Geometry to Graph},
  author = {Li, Yihui and Xiao, Jun and Zhou, Hao and Lin, Borong},
  year = 2026,
  month = mar,
  journal = {Automation in Construction},
  volume = {183},
  pages = {106815},
  issn = {0926-5805},
  doi = {10.1016/j.autcon.2026.106815},
}


@inproceedings{Li2024GraphConvex,
    author    = {Li, Yihui and Xiao, Jun and Zhou, Hao and Lin, Borong.},
    title     = {A Cross-Scale Normative Encoding Representation Method for 3D Building Models Suitable for Graph Neural Networks},
    booktitle = {Proceedings of the Building Simulation Conference 2025},
    publisher = {IBPSA},
    address   = {Brisbane, Australia},
    month     = {August},
    year      = {2025},
    pages     = {},
    doi       = {10.26868/25222708.2025.1305}
}
``` 
