Crosstech Core Ifc Schema Bridge

crosstech-core-ifc-schema-bridge

Quick Reference

IFC Entity Hierarchy (IFC4 / IFC4X3)

IfcRoot (abstract)
├── IfcObjectDefinition (abstract)
│   ├── IfcObject (abstract) — individual occurrences
│   │   ├── IfcProduct — physical/spatial objects with placement + shape
│   │   │   ├── IfcElement (walls, slabs, beams, columns, doors, windows)
│   │   │   ├── IfcSpatialElement (site, building, storey, space)
│   │   │   └── IfcAnnotation, IfcGrid, IfcPort
│   │   ├── IfcProcess, IfcControl, IfcResource, IfcActor, IfcGroup
│   ├── IfcTypeObject → IfcTypeProduct → IfcElementType
│   └── IfcContext → IfcProject
├── IfcRelationship (abstract) — objectified relationships
│   ├── IfcRelAggregates — spatial decomposition
│   ├── IfcRelContainedInSpatialStructure — element containment
│   ├── IfcRelDefinesByProperties — property attachment
│   ├── IfcRelDefinesByType — type assignment
│   ├── IfcRelAssociatesMaterial — material assignment
│   └── IfcRelVoidsElement — opening/void cutting
└── IfcPropertyDefinition → IfcPropertySet, IfcElementQuantity

Critical Warnings

NEVER convert IFC to another format without checking the schema version first. IFC4X3 entities are silently dropped by IFC4-only tools.

NEVER overwrite original IFC geometry with tessellated versions. Tessellation is a one-way operation that destroys parametric information.

NEVER query only occurrence-level properties. ALWAYS check both the occurrence AND its type object (IfcRelDefinesByType) for a complete property picture.

NEVER assume meters as the IFC unit. ALWAYS check units via ifcopenshell.util.unit.calculate_unit_scale(model) or parse IfcUnitAssignment.

NEVER rely solely on Three.js scene graph data for IFC properties. Properties are NOT stored in the scene graph — they MUST be queried via web-ifc separately.

NEVER assume IFC relationships map to parent-child trees. IFC relationships are many-to-many objectified entities. Flattening them to a tree ALWAYS loses information.

Technology Boundary

Side A: IFC Schema (the universal model)

IFC (Industry Foundation Classes) is the ISO-standardized data model for BIM.

Schema versions:

Core concepts:

• Entities: Typed objects inheriting from IfcRoot (GlobalId, Name, Description, OwnerHistory)
• Properties: Named value containers (IfcPropertySet) attached via IfcRelDefinesByProperties
• Quantities: Measured values (IfcElementQuantity) attached via the same relationship mechanism
• Relationships: Objectified links — each relationship is an entity itself with its own GlobalId
• Types: Shared definitions (IfcElementType) linked to occurrences via IfcRelDefinesByType
• Geometry: Parametric representations (extruded solids, swept solids, BREP, CSG)

IFC4X3 additions: IfcAlignment, IfcRoad, IfcRailway, IfcBridge, IfcMarineFacility, IfcFacilityPart, IfcCourse, IfcPavement, IfcBorehole, IfcGeomodel, IfcLinearElement. These entities do NOT exist in IFC4.

Side B: Target Formats (per-tool representation)

The Bridge: Mapping Rules

Schema mapping summary (full tables in references/methods.md):

Data loss matrix (what is LOST per target):

Critical Rules

1. ALWAYS check model.schema (IfcOpenShell) or ifcApi.GetModelSchema(modelID) (web-ifc) before processing any IFC file.
2. ALWAYS query properties from BOTH the occurrence AND its type. Use ifcopenshell.util.element.get_psets(element) which does this automatically.
3. ALWAYS apply unit conversion before using geometry or quantity values. Use ifcopenshell.util.unit.calculate_unit_scale(model).
4. ALWAYS maintain a parallel data structure for IFC semantic data when using Three.js (properties, relationships are NOT in the scene graph).
5. ALWAYS keep the original IFC file as the single source of truth for geometry. Tessellated exports are for display only.
6. NEVER flatten IFC objectified relationships to a simple tree without documenting what is lost.
7. NEVER assume all tools support IFC4X3. Infrastructure entities (IfcAlignment, IfcRoad) require explicit version checks.
8. NEVER compare property values across tools without normalizing string encoding. IFC uses ISO-8859-1 with \X2\ escape sequences.

Decision Tree

START: You have IFC data to use in another tool
│
├── Q1: What is the IFC schema version?
│   ├── IFC4 → All tools support this. Proceed.
│   ├── IFC4X3 → Check target tool support:
│   │   ├── IfcOpenShell 0.8.x → Supported
│   │   ├── web-ifc → Partial (verify geometry for infrastructure entities)
│   │   ├── FreeCAD NativeIFC → Partial (via IfcOpenShell)
│   │   └── Blender+Bonsai → Supported (via IfcOpenShell)
│   └── IFC2X3 → Legacy. Note: IfcWallStandardCase → IfcWall with PredefinedType
│
├── Q2: What data do you need in the target?
│   ├── Geometry only → Tessellation is acceptable. Use geometry engine.
│   ├── Properties + Geometry → MUST maintain parallel data channel (especially Three.js)
│   ├── Full semantic model → Use IfcOpenShell or FreeCAD NativeIFC
│   └── Transport between tools → Use Speckle (preserves properties, tessellates geometry)
│
├── Q3: Is round-trip editing required?
│   ├── YES → Use FreeCAD NativeIFC or Bonsai (keep IFC as source of truth)
│   └── NO → Tessellated export is acceptable for visualization
│
└── Q4: Target runtime?
    ├── Python (desktop/server) → IfcOpenShell
    ├── Browser → web-ifc + Three.js (or ThatOpen Components)
    ├── Blender → Bonsai extension (NEVER raw IFC import without Bonsai)
    ├── FreeCAD → NativeIFC mode (ALWAYS prefer over legacy import)
    └── Multi-tool pipeline → Speckle as transport layer

Essential Patterns

Pattern 1: Property Access Across Tools

The same IFC property (Pset_WallCommon.IsExternal) is accessed differently in each tool. See references/examples.md for complete code.

IfcOpenShell (one function call):

psets = ifcopenshell.util.element.get_psets(wall)
is_external = psets["Pset_WallCommon"]["IsExternal"]

web-ifc (manual relationship traversal required):

// Must traverse IfcRelDefinesByProperties → IfcPropertySet → IfcPropertySingleValue
// See references/examples.md for the full traversal pattern

Pattern 2: Schema Version Detection

# IfcOpenShell — ALWAYS check before processing
model = ifcopenshell.open("model.ifc")
schema = model.schema  # "IFC2X3", "IFC4", "IFC4X3"
if schema == "IFC4X3":
    alignments = model.by_type("IfcAlignment")  # Only in IFC4X3

// web-ifc — ALWAYS check before processing
const schema = ifcApi.GetModelSchema(modelID);  // "IFC4", "IFC2X3", etc.

Pattern 3: Relationship Types

IFC relationships are objectified — each relationship is an entity with its own ID. This is the primary source of data loss when converting to formats with simple parent-child trees.

Common Operations

Reading IFC Across Tools

IFC4 vs IFC4X3 Entity Mapping

Reference Links

• references/methods.md — IFC entity mapping tables for all target formats
• references/examples.md — Working code for reading/writing IFC across tools
• references/anti-patterns.md — Schema mapping mistakes and data loss patterns

Official Sources

• https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/ — IFC4 ADD2 TC1 schema
• https://ifc43-docs.standards.buildingsmart.org/ — IFC4X3 documentation
• https://docs.ifcopenshell.org/ — IfcOpenShell 0.8.x API
• https://github.com/ThatOpen/engine_web-ifc — web-ifc source and API
• https://docs.speckle.systems/developers/data-schema/connectors/ifc-schema — Speckle IFC mapping
• https://wiki.freecad.org/BIM_Workbench — FreeCAD BIM/NativeIFC