Metadata-Version: 2.4
Name: compas_ifc
Version: 2.0.0
Summary: High-level IFC interface for COMPAS.
Author-email: Tom Van Mele <van.mele@arch.ethz.ch>, Li Chen <li.chen@arch.ethz.ch>
License: MIT License
        
        ETH Zurich
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/compas-dev/compas_ifc
Project-URL: Documentation, https://compas.dev/compas_ifc/
Project-URL: Repository, https://github.com/compas-dev/compas_ifc.git
Project-URL: Changelog, https://github.com/compas-dev/compas_ifc/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/compas-dev/compas_ifc/issues
Project-URL: Forum, https://forum.compas-framework.org/
Keywords: compas,ifc,bim,interoperability
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: Unix
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: compas>=2.2
Requires-Dist: compas_model>=0.9.2
Requires-Dist: ifcopenshell==0.8.4.post1
Requires-Dist: lark
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: attrs>=17.4; extra == "dev"
Requires-Dist: black>=22.12.0; extra == "dev"
Requires-Dist: bump-my-version; extra == "dev"
Requires-Dist: compas_invocations2; extra == "dev"
Requires-Dist: invoke>=0.14; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: sphinx_compas2_theme; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Dynamic: license-file

# COMPAS IFC

![compas_ifc](compas_ifc.png)

A front-end data model for the [Industry Foundation Classes (IFC)](https://www.buildingsmart.org/standards/bsi-standards/industry-foundation-classes/),
the open BIM exchange standard maintained by buildingSMART International.
COMPAS IFC sits between IFC's full schema and the people who need to work with
it, exposing a small, intentional API where the schema offers thousands of
classes and dozens of relationship patterns.

The toolkit is the open-source artefact described in chapter 4 of *Future Data
Models for AEC: From Simplicity for Humans to Interoperability by AI* (Li Chen,
ETH Zürich, 2026). It targets researchers and developers who need to read,
analyse, modify, and write IFC data without becoming experts in the schema
itself.

## What it does

* Opens any IFC file (IFC2X3, IFC4, or IFC4X3) and exposes its content through
  one container class and one element class.
* Materialises the spatial hierarchy as an explicit
  [tree](https://compas.dev/compas/latest/api/generated/compas.datastructures.Tree.html)
  with direct parent/child pointers, so traversal does not require chasing
  `IfcRelContainedInSpatialStructure` instances.
* Materialises non-hierarchical relationships (structural connections, system
  flows, material associations, geometric dependencies) as a separate graph.
* Couples geometric representations to executable kernels — the COMPAS core
  library for primitives and meshes, OpenCascade (via
  [compas_occ](https://github.com/compas-dev/compas_occ)) for B-Rep and NURBS,
  and CGAL (via [compas_cgal](https://github.com/compas-dev/compas_cgal))
  for boolean operations and predicates — so volumes, surface areas, and
  bounding boxes can be computed without leaving Python.
* Treats every product subclass uniformly through a single `GenericElement`
  type, falling back to `IfcBuildingElementProxy` (with the original type name
  preserved as `ObjectType`) for custom or domain-specific elements.
* Validates element metadata against
  [Pydantic](https://docs.pydantic.dev/) schemas and rejects non-conforming
  data at the point of insertion.

## Architecture (three layers)

```
┌───────────────────────────────────────────────────────────────────┐
│ Front-end API                                                     │
│   BuildingInformationModel  GenericElement                        │
│   SpatialTree (model.tree)  InteractionGraph (model.graph)        │
└───────────────────────────────────────────────────────────────────┘
                                 ▲
┌───────────────────────────────────────────────────────────────────┐
│ Bidirectional mapping layer                                       │
│   relationship resolution · placement-chain rectification ·       │
│   representation conversion · type normalisation ·                │
│   property serialisation                                          │
└───────────────────────────────────────────────────────────────────┘
                                 ▲
┌───────────────────────────────────────────────────────────────────┐
│ IFC schema interface — IfcOpenShell (IFC2X3 · IFC4 · IFC4X3)      │
└───────────────────────────────────────────────────────────────────┘
```

## Installation

```bash
pip install compas_ifc
```

For development:

```bash
git clone https://github.com/compas-dev/compas_ifc.git
cd compas_ifc
pip install -e ".[dev]"
```

Optional dependencies:

* [compas_occ](https://github.com/compas-dev/compas_occ) — high-fidelity B-Rep
  and NURBS via OpenCascade.
* [compas_viewer](https://github.com/compas-dev/compas_viewer) —
  `model.show()` and `model.show_collisions()`.

## Quick start

```python
from compas_ifc.bim import BuildingInformationModel

# Load an existing model
model = BuildingInformationModel("data/Duplex_A_20110907.ifc")

# Walk the spatial hierarchy
for storey in model.storeys:
    print(storey.name)
    for child in storey.children:
        print(f"  - [{child.ifc_type}] {child.name}")

# Query by IFC type or GlobalId
walls = model.get_elements_by_type("IfcWall")
wall = model.get_element_by_global_id("3cUkl32yn9qRSPvBJZ3dB2")

# Computed geometric properties
print(wall.volume, wall.surface_area)

# Save back to disk
model.save("modified.ifc")
```

Creating a new model from scratch:

```python
from compas.geometry import Box, Frame, Point, Vector
from compas_ifc.bim import BuildingInformationModel

model = BuildingInformationModel.template(schema="IFC4", unit="m")
storey = model.storeys[0]

model.create_wall(
    name="South wall",
    parent=storey,
    geometry=Box(8.0, 0.2, 3.0),
    frame=Frame(Point(0, 0, 0), Vector.Xaxis(), Vector.Yaxis()),
)
model.save("from_scratch.ifc")
```

Custom elements with declarative validation:

```python
from pydantic import BaseModel, Field
from compas_ifc.bim import BuildingInformationModel
from compas_ifc.validation import Specification

class ConcreteRecipe(BaseModel):
    strength_class: str = Field(pattern=r"^C\d{2}/\d{2}$")
    cement_type: str
    cover_mm: float = Field(gt=0)

model = BuildingInformationModel.template(schema="IFC4", unit="m")
model.specifications = [
    Specification(
        name="Concrete recipe",
        ifc_types=["IfcSlab"],
        required_psets={"ConcreteRecipe": ConcreteRecipe},
    )
]
# Slabs added without a valid ConcreteRecipe pset are rejected at insertion.
```

## Verifying the thesis claims

The complete evaluation suite from appendix A of the thesis lives in
`thesis/appendix/A/`. Run them all and produce a consolidated report with:

```bash
conda run -n compas-ifc python thesis/appendix/A/run_all.py
```

The report is written to `thesis/appendix/A/outputs/A-summary.txt`.

## Project structure

```
compas_ifc/
├── src/compas_ifc/
│   ├── bim.py             # BuildingInformationModel — entry point
│   ├── element.py         # GenericElement — unified element abstraction
│   ├── factory.py         # ElementFactoryMixin — typed creators + template
│   ├── tree.py            # TreeMixin — IFC import/export, placement rectify
│   ├── interactions.py    # InteractionMixin — graph + connection/collision
│   ├── validation.py      # Specification + Pydantic-based enforcement
│   ├── representations/   # Parametric geometry (Extrusion, Pipe, …)
│   ├── brep/              # TessellatedBrep + viewer plugins
│   ├── algorithms/        # Vectorised contact and collision detection
│   ├── conversions/       # IFC ↔ COMPAS converters
│   ├── entities/          # IfcOpenShell wrappers (back-end implementation)
│   └── file.py            # IFCFile — ifcopenshell adapter
├── tests/                 # pytest suite
├── thesis/appendix/A/     # Reproducible evaluation suite (chapter 4)
├── data/                  # Reference IFC files
├── docs/                  # Sphinx documentation
└── scripts/               # Worked examples
```

## License

MIT. See [LICENSE](LICENSE).

## Citing

If you use COMPAS IFC in academic work, please cite the thesis:

> Chen, L. *Future Data Models for AEC: From Simplicity for Humans to
> Interoperability by AI*. Doctoral dissertation, ETH Zürich, 2026.

## Contact

Issues and feature requests: <https://github.com/compas-dev/compas_ifc/issues>.
Questions: <li.chen@arch.ethz.ch>.
