Crosstech Core Coordinate Systems

crosstech-core-coordinate-systems

Quick Reference

Key EPSG Codes for AEC

Axis Conventions by Tool

Critical Warnings

NEVER use pyproj without always_xy=True — EPSG:4326 defaults to (lat, lon) order, causing silent coordinate swaps.

NEVER import IFC into GIS without checking for IfcMapConversion — models without georeferencing land at (0°N, 0°E) in the Gulf of Guinea.

NEVER mix UTM zones in a single project — coordinates from adjacent zones differ by hundreds of kilometers in easting.

NEVER confuse NAP height with WGS84 ellipsoidal height — the ~42m difference in the Netherlands causes buildings to float above terrain.

NEVER hardcode TOWGS84 parameters — use EPSG codes via pyproj, which selects the best available transformation automatically.

ALWAYS apply Y/Z swap when moving data between Z-up (BIM/GIS) and Y-up (Three.js) environments.

ALWAYS verify georeferencing by overlaying the result on a known map — visual checks catch errors that math alone misses.

Technology Boundary

Side A: BIM Local Coordinates

BIM authoring tools use local coordinate systems with no inherent geographic meaning. Geometry sits at or near local origin (0,0,0).

Key concepts:

• Revit Internal Origin: Fixed at (0,0,0), immutable. Survey Point defines real-world relationship. Internal units: feet (1 ft = 0.3048 m exactly).
• Blender World Origin: (0,0,0). Default units: meters. Bonsai handles georeferencing via IFC entities.
• FreeCAD World Origin: (0,0,0). Internal units: millimeters.
• Typical coordinate range: 0 to 500,000 mm (large building ~500m span).

IFC project units are defined in IfcProject → IfcUnitAssignment. Common values: meters (m) or millimeters (mm). The IfcMapConversion.Scale factor converts from project units to CRS map units.

Side B: GIS Global Coordinates (CRS-based)

GIS tools use Coordinate Reference Systems (CRS) to map coordinates to real-world locations on Earth.

Two CRS types:

• Geographic CRS: Latitude/longitude in degrees on an ellipsoid (e.g., EPSG:4326 WGS84). No distortion but not usable for engineering measurements.
• Projected CRS: Easting/northing in meters on a flat plane (e.g., EPSG:28992 RD New). ALWAYS introduces some distortion. Required for engineering work.

Datum transformations between different ellipsoids are ALWAYS lossy:

• 7-parameter Helmert: 1–5 m accuracy
• Grid-based (NTv2/GTX): 1–10 cm accuracy
• Same-datum reprojections: lossless (float precision only)

The Bridge: IfcMapConversion + pyproj Transformation

The bridge between BIM local and GIS global has two stages:

Stage 1 — IfcMapConversion (local BIM → projected CRS):

E = Scale * (x * XAxisAbscissa - y * XAxisOrdinate) + Eastings
N = Scale * (x * XAxisOrdinate + y * XAxisAbscissa) + Northings
H = Scale * z + OrthogonalHeight

Where:

• (x, y, z) = local BIM coordinates
• (E, N, H) = map coordinates in the target CRS
• XAxisAbscissa = cos(θ), XAxisOrdinate = sin(θ) where θ = true north rotation
• Scale converts project units to CRS units (e.g., 0.001 for mm→m)

Stage 2 — pyproj (projected CRS → any other CRS):

from pyproj import Transformer
transformer = Transformer.from_crs("EPSG:28992", "EPSG:4326", always_xy=True)
lon, lat = transformer.transform(easting, northing)

IFC entities involved:

IFC4 vs IFC4X3 differences:

Critical Rules (ALWAYS/NEVER)

1. ALWAYS set always_xy=True in pyproj Transformer.from_crs() calls.
2. ALWAYS check for both IfcMapConversion AND IfcProjectedCRS before BIM→GIS conversion.
3. ALWAYS verify that IfcMapConversion.Scale matches the ratio between project units and CRS units.
4. ALWAYS use IfcProjectedCRS.Name in the format "EPSG:XXXXX" for unambiguous CRS identification.
5. ALWAYS validate coordinates fall within the valid range for the assigned CRS after transformation.
6. ALWAYS use ifcopenshell.util.geolocation.auto_xyz2enh when the IFC file contains georeferencing — it reads parameters directly from the model.
7. NEVER assume model units — read them from IfcProject → IfcUnitAssignment.
8. NEVER use EPSG:3857 (Web Mercator) for engineering work — it distorts areas and distances significantly.
9. NEVER omit the Y/Z swap when transferring between Z-up and Y-up systems.
10. NEVER mix vertical datums (NAP vs ellipsoidal) in a single pipeline without explicit conversion.

Decision Tree

Is this a BIM → GIS conversion?
├─ YES → Does the IFC file contain IfcMapConversion?
│   ├─ YES → Use auto_xyz2enh() for local → projected CRS
│   │   └─ Need a different target CRS?
│   │       ├─ YES → Chain with pyproj Transformer
│   │       └─ NO → Done (coordinates are in IfcProjectedCRS target)
│   └─ NO → STOP. Georeferencing MUST be added first.
│       └─ Use ifcopenshell.api.run("georeference.add_georeferencing")
│
Is this a GIS → BIM conversion?
├─ YES → Use pyproj to get coordinates in the IFC's target CRS
│   └─ Then use enh2xyz() to convert to local BIM coordinates
│
Is this a BIM → Web viewer (Three.js) conversion?
├─ YES → Apply Y/Z swap: Three.js_y = BIM_z, Three.js_z = -BIM_y
│   └─ Georeferencing needed? → First do BIM → GIS, then GIS → viewer
│
Is the model appearing at the wrong location?
├─ YES → See "Common Failures" in references/anti-patterns.md
│   ├─ At (0,0) / Gulf of Guinea? → Missing IfcMapConversion
│   ├─ Hundreds of km off? → Wrong EPSG code or UTM zone mismatch
│   ├─ ~42m vertical offset (NL)? → NAP vs ellipsoidal height confusion
│   ├─ 1000x too large/small? → Unit mismatch (mm vs m)
│   └─ Rotated on map? → Wrong XAxisAbscissa/XAxisOrdinate values

Essential Patterns

Pattern 1: Check for Georeferencing

import ifcopenshell

ifc = ifcopenshell.open("model.ifc")
has_georef = len(ifc.by_type("IfcMapConversion")) > 0
has_crs = len(ifc.by_type("IfcProjectedCRS")) > 0

if not has_georef or not has_crs:
    raise ValueError("Model lacks georeferencing — cannot place on map")

Pattern 2: Local to Map Coordinates (IfcOpenShell)

import ifcopenshell.util.geolocation as geo

# Auto-reads IfcMapConversion from the file
e, n, h = geo.auto_xyz2enh(ifc, local_x, local_y, local_z)

Pattern 3: CRS Reprojection (pyproj)

from pyproj import Transformer

transformer = Transformer.from_crs("EPSG:28992", "EPSG:4326", always_xy=True)
lon, lat = transformer.transform(easting, northing)

Pattern 4: BIM Z-up to Three.js Y-up

function bimToThreeJs(x, y, z) {
    return { x: x, y: z, z: -y };
}

The negation of Y→Z preserves the right-handed coordinate system.

Pattern 5: Add Georeferencing to IFC

import ifcopenshell
import ifcopenshell.api

ifc = ifcopenshell.open("model.ifc")
ifcopenshell.api.run("georeference.add_georeferencing", ifc)
ifcopenshell.api.run("georeference.edit_georeferencing", ifc,
    projected_crs={"Name": "EPSG:28992"},
    coordinate_operation={
        "Eastings": 155000.0,
        "Northings": 463000.0,
        "OrthogonalHeight": 0.0,
        "XAxisAbscissa": 1.0,
        "XAxisOrdinate": 0.0,
        "Scale": 1.0
    }
)
ifc.write("georeferenced_model.ifc")

Common Operations

Validate CRS Coordinate Ranges

True North Rotation Encoding

For a θ-degree anti-clockwise True North rotation:

XAxisAbscissa = cos(θ)
XAxisOrdinate = sin(θ)

Example: 30° rotation → XAxisAbscissa = 0.866025, XAxisOrdinate = 0.5

Vertical Datum: NAP vs Ellipsoidal

In the Netherlands, NAP heights differ from WGS84 ellipsoidal heights by ~42–44 meters (geoid undulation). For 3D transformations, use compound CRS EPSG:7415 (RD New + NAP) with pyproj to handle vertical conversion automatically.

Reference Links

• references/methods.md — CRS transformation APIs: pyproj, IfcOpenShell georef, PROJ pipeline syntax
• references/examples.md — Working transformation code examples for all patterns
• references/anti-patterns.md — Coordinate system mistakes and how to diagnose them

Official Sources

• https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/ (IFC4 specification)
• https://ifc43-docs.standards.buildingsmart.org/ (IFC4X3 specification)
• https://proj.org/en/stable/ (PROJ documentation)
• https://pyproj4.github.io/pyproj/stable/ (pyproj documentation)
• https://docs.ifcopenshell.org/ (IfcOpenShell documentation)
• https://epsg.io (EPSG registry lookup)