ifc-syntax-georeferencing

name	ifc-syntax-georeferencing
description	Use when you need to anchor an IFC model to real-world geographic coordinates : declare where the local project origin sits on Earth, rotate the model onto a map grid, pick between coarse site latitude/longitude and a precise projected CRS, or place infrastructure objects along an alignment by station and offset. Prevents treating the coarse IfcSite latitude as precise georeferencing, applying the map-conversion translation and rotation in the wrong order, mixing signs in a compound plane angle, targeting a map conversion at a non-projected CRS, emitting IFC4 or IFC4.3 georeferencing entities into an IFC2x3 file, and authoring geometry at raw projected coordinates. Covers IfcSite RefLatitude / RefLongitude / RefElevation, IfcCompoundPlaneAngleMeasure, IfcMapConversion, IfcProjectedCRS, IfcCoordinateReferenceSystem, IfcCoordinateOperation, IfcMapConversionScaled, the IFC4.3 IfcLinearPlacement family, the LoGeoRef levels, and the IFC2x3 / IFC4 / IFC4.3 version differences. Keywords: IFC georeferencing, IfcMapConversion, IfcProjectedCRS, IfcCoordinateReferenceSystem, IfcCoordinateOperation, IfcMapConversionScaled, IfcSite, RefLatitude, RefLongitude, RefElevation, IfcCompoundPlaneAngleMeasure, Eastings, Northings, OrthogonalHeight, XAxisAbscissa, XAxisOrdinate, EPSG, UTM, WGS84, ETRS89, projected CRS, true north, IfcLinearPlacement, IfcAxis2PlacementLinear, IfcPointByDistanceExpression, station, chainage, LoGeoRef, my model is in the wrong place, model not on the map, how do I set coordinates, model rotated wrong, coordinates too large, IFC2x3, IFC4, IFC4.3.
license	MIT
compatibility	Designed for Claude Code. Requires IFC IFC2x3, IFC4, IFC4.3.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

IFC Syntax : Georeferencing

IFC geometry is authored in a flat, metre-scale local engineering coordinate system. Georeferencing is the separate, additive layer that tells a consumer where that local origin sits on Earth and how it is rotated onto a map grid. This skill covers the three generations of georeferencing mechanism, the entities they use, the transformation order, and the version availability.

Legacy site coordinates exist in IFC2x3, IFC4, and IFC4.3. Precise georeferencing (IfcMapConversion, IfcProjectedCRS) is IFC4 and later. Linear placement is IFC4.3 only. The Version Differences section is load-bearing.

Quick Reference

The three mechanisms

Coarse legacy  (IFC2x3, IFC4, IFC4.3)
  IfcSite.RefLatitude / RefLongitude / RefElevation
  One anchor point, WGS84 angular, NO rotation. Sun-shading accuracy only.

Precise        (IFC4, IFC4.3)
  IfcMapConversion + IfcProjectedCRS
  Full scale + rotation + translation into a projected map CRS. Survey accuracy.

Linear         (IFC4.3 only)
  IfcLinearPlacement + IfcAxis2PlacementLinear + IfcPointByDistanceExpression
  Positions infrastructure objects by station and offset along an alignment curve.

ALWAYS use IfcMapConversion plus IfcProjectedCRS when survey, GIS hand-off, or infrastructure coordination accuracy is needed. NEVER rely on IfcSite latitude and longitude for precise placement : the specification states they are not meant to replace precise georeferencing.

Legacy : IfcSite reference coordinates

IfcSite carries three optional reference attributes, present in every IFC version :

• RefLatitude : OPTIONAL IfcCompoundPlaneAngleMeasure. World latitude at the reference point, relative to WGS84.
• RefLongitude : OPTIONAL IfcCompoundPlaneAngleMeasure. World longitude, relative to WGS84.
• RefElevation : OPTIONAL IfcLengthMeasure. Datum elevation relative to sea level.

IfcCompoundPlaneAngleMeasure is verified verbatim :

TYPE IfcCompoundPlaneAngleMeasure = LIST [3:4] OF INTEGER;

Element 1 is degrees, 2 is minutes, 3 is seconds, optional 4 is millionths of a second. ALL non-zero components must share one sign. A southern latitude of 51 degrees 30 minutes 26 seconds is (-51, -30, -26), NEVER (-51, 30, 26).

This mechanism locates one point and carries no rotation. The model's bearing onto the map is unknown from the site point alone.

Precise : IfcMapConversion

IfcMapConversion is a new entity in IFC4. It expresses the full rigid transform from the local engineering CRS into a projected map CRS. Verified verbatim (IFC4.3) :

ENTITY IfcMapConversion
 SUPERTYPE OF (ONEOF (IfcMapConversionScaled))
 SUBTYPE OF (IfcCoordinateOperation);
	Eastings : IfcLengthMeasure;
	Northings : IfcLengthMeasure;
	OrthogonalHeight : IfcLengthMeasure;
	XAxisAbscissa : OPTIONAL IfcReal;
	XAxisOrdinate : OPTIONAL IfcReal;
	Scale : OPTIONAL IfcReal;
 WHERE
	TargetCRSOnlyProjected : 'IFC4X3_DEV.IFCPROJECTEDCRS'
		IN TYPEOF(SELF\IfcCoordinateOperation.TargetCRS);
END_ENTITY;

• Eastings, Northings, OrthogonalHeight : required. The translation of the local origin in the map CRS.
• XAxisAbscissa, XAxisOrdinate : optional. The local X axis expressed as a 2D direction in the map easting/northing plane. Together they encode the grid bearing.
• Scale : optional, defaults to 1.0. A single uniform scale factor.
• SourceCRS, TargetCRS : inherited from IfcCoordinateOperation. SourceCRS is the project's IfcGeometricRepresentationContext; TargetCRS must be an IfcProjectedCRS (the TargetCRSOnlyProjected rule enforces it).

The IFC4 baseline definition is identical except it has no WHERE rule and no IfcMapConversionScaled subtype.

The transformation order

The map conversion applies, in this exact sequence :

1. SCALE       : multiply x, y, z by Scale (uniform).
2. ROTATE      : anti-clockwise about the Z axis by
                 theta = arctan(XAxisOrdinate / XAxisAbscissa).
3. TRANSLATE   : add (Eastings, Northings, OrthogonalHeight).

ALWAYS compose the matrix as T * R * S (translation outermost). NEVER translate before rotating, and NEVER rotate before scaling : the order is load-bearing and any other order mis-places every element.

Precise : IfcProjectedCRS

IfcProjectedCRS describes the target projected CRS : datum, projection, zone. A new entity in IFC4. Verified verbatim (IFC4.3) :

ENTITY IfcProjectedCRS
 SUBTYPE OF (IfcCoordinateReferenceSystem);
	VerticalDatum : OPTIONAL IfcIdentifier;
	MapProjection : OPTIONAL IfcIdentifier;
	MapZone : OPTIONAL IfcIdentifier;
	MapUnit : OPTIONAL IfcNamedUnit;
 WHERE
	MapUnitIsLength : NOT(EXISTS(SELF.MapUnit)) OR
		(SELF.MapUnit.UnitType = IfcUnitEnum.LENGTHUNIT);
END_ENTITY;

Name, Description, GeodeticDatum are inherited from IfcCoordinateReferenceSystem. Typical values : Name = 'EPSG:25832', GeodeticDatum = 'ETRS89', MapProjection = 'UTM', MapZone = '32N'. The MapUnitIsLength rule requires MapUnit, if present, to be a length unit.

IFC4.3 : linear placement

IfcLinearPlacement positions an object by station and offset along an alignment curve, instead of by an absolute Cartesian triple. It is IFC4.3 only. Verified verbatim :

ENTITY IfcLinearPlacement
 SUBTYPE OF (IfcObjectPlacement);
	RelativePlacement : IfcAxis2PlacementLinear;
	CartesianPosition : OPTIONAL IfcAxis2Placement3D;
END_ENTITY;

RelativePlacement is an IfcAxis2PlacementLinear whose inherited Location is an IfcPointByDistanceExpression (carrying DistanceAlong, the station, plus lateral and vertical offsets and a BasisCurve). CartesianPosition is the optional Cartesian fallback for consumers that do not implement linear referencing.

ALWAYS write CartesianPosition alongside an IfcLinearPlacement : a geometry-only consumer that lacks linear referencing cannot place the object without it.

LoGeoRef levels (informative)

LoGeoRef (Level of Georeferencing) is an informative academic classification, NOT part of the IFC schema. Levels 10 to 50, higher is better. Level 20 is IfcSite latitude/longitude; level 50 is IfcMapConversion plus IfcProjectedCRS. Level 50 requires IFC4 or later. NEVER cite LoGeoRef as a buildingSMART normative rule.

Version differences (compact)

Entity / mechanism	IFC2x3	IFC4	IFC4.3
IfcSite Ref latitude / longitude / elevation	yes	yes	yes
IfcCompoundPlaneAngleMeasure	yes	yes	yes
IfcMapConversion, IfcProjectedCRS	no	yes	yes
IfcCoordinateOperation, IfcCoordinateReferenceSystem	no	yes	yes
IfcMapConversion WHERE rule + WKT inverse	no	no	yes
IfcMapConversionScaled	no	no	yes
IfcLinearPlacement family	no	no	yes
LoGeoRef 50 achievable	no	yes	yes

Decision Trees

Coarse or precise georeferencing?

How accurate must the model's real-world position be?
|
+-- Sun-shading, rough context, no survey hand-off
|   --> IfcSite.RefLatitude / RefLongitude / RefElevation is enough.
|       Coarse, all IFC versions, no rotation.
|
+-- Survey accuracy, GIS hand-off, infrastructure coordination
|   --> IfcMapConversion + IfcProjectedCRS. IFC4 or later only.
|
+-- The file must be IFC2x3 and still georeferenced
    --> IfcSite lat/long is the best available. Precise entities do
        NOT exist in IFC2x3. Add TrueNorth on the representation
        context for an approximate bearing.

Which target CRS?

What is IfcMapConversion.TargetCRS?
|
+-- ALWAYS an IfcProjectedCRS (a linear, projected map CRS).
|   The TargetCRSOnlyProjected WHERE rule enforces this.
|
+-- NEVER an IfcGeographicCRS or any non-projected CRS : the rule
    rejects it, and an angular CRS has no metric eastings/northings.

Cartesian or linear placement?

How is the object naturally located?
|
+-- By an X/Y/Z position in the building
|   --> IfcLocalPlacement (see ifc-syntax-geometry-placement).
|
+-- By a structural grid intersection
|   --> IfcGridPlacement.
|
+-- By a station and offset along a road / rail / bridge alignment
    --> IfcLinearPlacement (IFC4.3 only). ALWAYS add the
        CartesianPosition fallback.

Patterns

Pattern : Use IfcSite coordinates only for coarse context

ALWAYS treat IfcSite.RefLatitude, RefLongitude, and RefElevation as a coarse anchor point suitable for sun-shading and rough siting. NEVER present the site latitude and longitude as precise georeferencing : the IfcSite specification states they are not meant to replace it, they carry no grid rotation, and they mix an angular datum with a flat Cartesian model.

Pattern : Keep compound plane angle signs consistent

ALWAYS make every non-zero component of an IfcCompoundPlaneAngleMeasure carry the same sign. A western longitude of 0 degrees 7 minutes 39 seconds is (0, -7, -39). NEVER mix signs ((-51, 30, 26)) : the WHERE rule on the measure requires sign consistency and the buildingSMART validation service flags a violation.

Pattern : Wire the map conversion to the representation context

ALWAYS set IfcMapConversion.SourceCRS to the project's 3D model IfcGeometricRepresentationContext : the IfcCoordinateReferenceSystemSelect type permits it precisely because that context is the local engineering CRS. ALWAYS set IfcMapConversion.TargetCRS to an IfcProjectedCRS. There is no direct attribute on IfcProject for the map conversion : the link runs through the representation context acting as SourceCRS.

See ifc-syntax-geometry-placement for the placement tree and the representation context.

Pattern : Apply the transformation in scale-rotate-translate order

ALWAYS apply the map conversion as scale first, then anti-clockwise Z rotation, then translation, and compose the 4x4 matrix as T * R * S. ALWAYS derive the rotation angle as arctan(XAxisOrdinate / XAxisAbscissa). NEVER translate before rotating or rotate before scaling : the order is fixed by the specification and any other order mis-places every element.

Pattern : Always express the grid bearing

ALWAYS populate XAxisAbscissa and XAxisOrdinate when the model's local X axis is not parallel to map easting. They express the local X axis as a 2D direction in the map plane. NEVER omit the X-axis direction pair on a rotated model : when both are absent the consumer applies no rotation and the model is silently mis-oriented on the map.

Pattern : Keep geometry near a local origin

ALWAYS author building geometry near a local origin, with coordinates in the metre-to-kilometre range, and express the real-world offset only through IfcMapConversion. NEVER author geometry at raw projected eastings and northings (coordinates in the millions of metres) : large coordinate values destroy floating-point precision in downstream geometry kernels.

Pattern : Provide the linear-placement fallback

ALWAYS write IfcLinearPlacement.CartesianPosition (an IfcAxis2Placement3D) alongside the linear RelativePlacement when exporting an IFC4.3 infrastructure model. NEVER ship a linear placement without the Cartesian fallback : a consumer that does not implement linear referencing then cannot place the object at all.

Pattern : Honour the version availability

ALWAYS restrict IfcMapConversion, IfcProjectedCRS, IfcCoordinateOperation, and IfcCoordinateReferenceSystem to IFC4 and IFC4.3 files. ALWAYS restrict IfcLinearPlacement, IfcAxis2PlacementLinear, IfcPointByDistanceExpression, and IfcMapConversionScaled to IFC4.3 files. NEVER emit any of these into an IFC2x3 file : they do not exist in the IFC2x3 schema and the file fails validation. See ifc-core-version-evolution.

Reference Links

• references/methods.md : the complete verified EXPRESS definitions and attribute tables for every georeferencing entity, the abstract supertypes, the select type, and the full version-availability matrix.
• references/examples.md : worked STEP scenarios : a legacy IfcSite reference point, a complete IfcMapConversion plus IfcProjectedCRS block, an IfcLinearPlacement, and reading a point through the transformation.
• references/anti-patterns.md : the failure modes this skill prevents, each with the rule or version reason it violates.

Official sources

• IfcSite : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcSite.htm
• IfcCompoundPlaneAngleMeasure : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcCompoundPlaneAngleMeasure.htm
• IfcMapConversion : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcMapConversion.htm
• IfcProjectedCRS : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcProjectedCRS.htm
• IfcCoordinateReferenceSystem : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcCoordinateReferenceSystem.htm
• IfcCoordinateOperation : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcCoordinateOperation.htm
• IfcLinearPlacement : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcLinearPlacement.htm
• IfcMapConversion (IFC4) : https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/schema/ifcrepresentationresource/lexical/ifcmapconversion.htm

Related skills

• ifc-syntax-geometry-placement : the local placement tree and the IfcGeometricRepresentationContext that acts as the map-conversion SourceCRS.
• ifc-core-version-evolution : which entities exist in which IFC version.