SuperAPI AI Directory

ifc-syntax-geometry-placement

General & other

View repository

Updated 10-16 09:56

About this skill

IFC Syntax : Geometry Placement

IFC stores an element's shape and its position separately. The geometry items inside a representation are defined in a local coordinate system whose origin is (0,0,0). Where that local system sits in the world is carried by IfcProduct.ObjectPlacement, an IfcObjectPlacement.

This skill covers the placement tree : how placements chain parent to child, how an axis placement defines a coordinate system, and how a consumer resolves a product to world coordinates. Georeferencing (IfcMapConversion, IfcProjectedCRS, the IfcSite reference latitude/longitude) is a separate concern : see ifc-syntax-georeferencing.

Applies to IFC2x3, IFC4, and IFC4.3. One attribute moved between versions and IFC4.3 added a third placement subtype : see the Version Differences section.

Quick Reference

IfcObjectPlacement : the placement supertype

Verified verbatim (IFC4.3) :

ENTITY IfcObjectPlacement
 ABSTRACT SUPERTYPE OF (ONEOF
	(IfcGridPlacement
	,IfcLinearPlacement
	,IfcLocalPlacement));
	PlacementRelTo : OPTIONAL IfcObjectPlacement;
 INVERSE
	PlacesObject : SET [0:?] OF IfcProduct FOR ObjectPlacement;
	ReferencedByPlacements : SET [0:?] OF IfcObjectPlacement FOR PlacementRelTo;
END_ENTITY;
  • IfcObjectPlacement is abstract : NEVER instantiate it directly. Use a concrete subtype.
  • PlacementRelTo is the link to the parent placement. When omitted, the placement is absolute in the project world coordinate system.
  • PlacesObject (inverse) gives the products positioned by this placement.
  • In IFC4.3 PlacementRelTo is on IfcObjectPlacement, so every placement type chains. In IFC2x3 and IFC4 PlacementRelTo was on IfcLocalPlacement only. IfcLinearPlacement is an IFC4.3 addition : IFC2x3 and IFC4 have only IfcGridPlacement and IfcLocalPlacement.

IfcLocalPlacement : the common placement

Verified verbatim (IFC4.3) :

ENTITY IfcLocalPlacement
 SUBTYPE OF (IfcObjectPlacement);
	RelativePlacement : IfcAxis2Placement;
 WHERE
	WR21 : IfcCorrectLocalPlacement(RelativePlacement, PlacementRelTo);
END_ENTITY;
  • RelativePlacement (IfcAxis2Placement, required) is the transformation from this element's local system into the parent's system.
  • PlacementRelTo is inherited (IFC4.3) or local (IFC2x3 / IFC4). When present it names the parent placement ; when absent the placement is absolute.
  • WR21 (IfcCorrectLocalPlacement) enforces dimensional consistency : a 3D RelativePlacement may only chain to a 3D parent placement.

IfcAxis2Placement is a SELECT over IfcAxis2Placement2D and IfcAxis2Placement3D (and IfcAxis2PlacementLinear in IFC4.3).

The placement tree

PlacementRelTo chains placements into a tree that mirrors the spatial structure :

IfcProject  (world coordinate system, the root)
  ^
IfcSite           placement PlacementRelTo -> none (or the project context)
  ^
IfcBuilding       placement PlacementRelTo -> site placement
  ^
IfcBuildingStorey placement PlacementRelTo -> building placement
  ^
IfcWall           placement PlacementRelTo -> storey placement
  ^
IfcDoor           placement PlacementRelTo -> wall placement

Each level's RelativePlacement is the transform into its parent. ALWAYS set a child element's PlacementRelTo to its spatial-structure parent's placement. NEVER leave every element absolute : a model where each element is independently absolute cannot be moved as a unit and breaks when the storey is repositioned.

Resolving to world coordinates

A product's world transform is the product of every RelativePlacement matrix from the element up the PlacementRelTo chain to the root :

M_world(door) = M(site) x M(building) x M(storey) x M(wall) x M(door)

ALWAYS multiply the entire chain to obtain world coordinates. NEVER read a single RelativePlacement as a world position : a RelativePlacement is relative to the parent, not to the world, unless PlacementRelTo is absent.

IfcAxis2Placement3D : a 3D coordinate system

Verified verbatim (IFC4.3) :

ENTITY IfcAxis2Placement3D
 SUBTYPE OF (IfcPlacement);
	Axis : OPTIONAL IfcDirection;
	RefDirection : OPTIONAL IfcDirection;
 DERIVE
	P : LIST [3:3] OF IfcDirection := IfcBuildAxes(Axis, RefDirection);
 WHERE
	AxisAndRefDirProvision : NOT ((EXISTS (Axis)) XOR (EXISTS (RefDirection)));
	AxisIs3D : (NOT (EXISTS (Axis))) OR (Axis.Dim = 3);
	AxisToRefDirPosition : (NOT (EXISTS (Axis))) OR (NOT (EXISTS (RefDirection)))
		OR (IfcCrossProduct(Axis,RefDirection).Magnitude > 0.0);
	LocationIs3D : SELF\IfcPlacement.Location.Dim = 3;
	RefDirIs3D : (NOT (EXISTS (RefDirection))) OR (RefDirection.Dim = 3);
END_ENTITY;
  • Location is inherited from IfcPlacement : the origin, an IfcCartesianPoint.
  • Axis is the Z axis (IfcDirection). Default when omitted : [0,0,1].
  • RefDirection approximates the X axis. Default when omitted : [1,0,0].
  • The Y axis is derived by IfcBuildAxes as the cross product, and RefDirection is re-orthogonalised against Axis to yield a right-handed system.
  • AxisAndRefDirProvision : Axis and RefDirection MUST be both present or both omitted. Supplying exactly one fails the rule.
  • AxisToRefDirPosition : Axis and RefDirection MUST NOT be parallel : a zero cross-product magnitude cannot form a coordinate system.

IfcAxis2Placement2D : a 2D coordinate system

Verified verbatim (IFC4.3) :

ENTITY IfcAxis2Placement2D
 SUBTYPE OF (IfcPlacement);
	RefDirection : OPTIONAL IfcDirection;
 DERIVE
	P : LIST [2:2] OF IfcDirection := IfcBuild2Axes(RefDirection);
 WHERE
	LocationIs2D : SELF\IfcPlacement.Location.Dim = 2;
	RefDirIs2D : (NOT (EXISTS (RefDirection))) OR (RefDirection.Dim = 2);
END_ENTITY;

It has no Axis : a 2D system has only Location and RefDirection (the X axis, default [1,0]). The Y axis is derived perpendicular to it.

IfcCartesianPoint and IfcDirection

ENTITY IfcCartesianPoint
 SUBTYPE OF (IfcPoint);
	Coordinates : LIST [1:3] OF IfcLengthMeasure;
 WHERE
	CP2Dor3D : HIINDEX(Coordinates) >= 2;
END_ENTITY;
ENTITY IfcDirection
 SUBTYPE OF (IfcGeometricRepresentationItem);
	DirectionRatios : LIST [2:3] OF IfcReal;
 DERIVE
	Dim : IfcDimensionCount := HIINDEX(DirectionRatios);
 WHERE
	MagnitudeGreaterZero : SIZEOF(QUERY(Tmp <* DirectionRatios | Tmp <> 0.0)) > 0;
END_ENTITY;
  • IfcCartesianPoint.Coordinates holds 2 or 3 length values (CP2Dor3D forbids a 1D point in practice).
  • IfcDirection.DirectionRatios holds 2 or 3 ratios. A direction MUST have a non-zero magnitude : an all-zero direction fails MagnitudeGreaterZero.
  • IfcDirection is a direction, NOT a point : it carries no unit and is treated as normalised.

IfcGridPlacement : placement on a structural grid

Verified verbatim (IFC4.3) :

ENTITY IfcGridPlacement
 SUBTYPE OF (IfcObjectPlacement);
	PlacementLocation : IfcVirtualGridIntersection;
	PlacementRefDirection : OPTIONAL IfcGridPlacementDirectionSelect;
END_ENTITY;
ENTITY IfcVirtualGridIntersection;
	IntersectingAxes : LIST [2:2] OF UNIQUE IfcGridAxis;
	OffsetDistances : LIST [2:3] OF IfcLengthMeasure;
END_ENTITY;
  • PlacementLocation is an IfcVirtualGridIntersection : the meeting point of exactly two IfcGridAxis instances, with OffsetDistances shifting the point off the exact intersection.
  • PlacementRefDirection (IfcGridPlacementDirectionSelect : an IfcDirection or an IfcVirtualGridIntersection) orients the X axis. When omitted the grid axis tangent is used.
  • IfcGridPlacement positions an object on the design grid. See IfcGrid and IfcGridAxis in ifc-syntax-geometry-representations.

Version differences (compact)

Item IFC2x3 IFC4 IFC4.3
PlacementRelTo declared on IfcLocalPlacement IfcLocalPlacement IfcObjectPlacement
IfcObjectPlacement subtypes Grid, Local Grid, Local Grid, Linear, Local
IfcLinearPlacement absent absent present
IfcAxis2PlacementLinear absent absent present

The placement-tree mechanics, IfcLocalPlacement, the axis placements, IfcCartesianPoint, IfcDirection, and IfcGridPlacement are identical in syntax across all three versions ; only the location of PlacementRelTo and the extra IFC4.3 linear subtype differ.

Decision Trees

Which placement subtype?

How is the object positioned?
|
+-- Relative to another element or spatial container (the normal case)
|   --> IfcLocalPlacement, PlacementRelTo set to the parent's placement.
|
+-- On a structural design grid, at a grid-axis intersection
|   --> IfcGridPlacement with an IfcVirtualGridIntersection.
|
+-- Along an alignment / linear referencing curve (infrastructure)  [IFC4.3 only]
    --> IfcLinearPlacement. See ifc-syntax-georeferencing.

Absolute or relative placement?

Does this object sit inside a spatial container or host element?
|
+-- YES (a wall in a storey, a door in a wall) : ALWAYS relative.
|   --> set PlacementRelTo to the parent's IfcObjectPlacement.
|
+-- NO, it is the spatial root (IfcSite at project origin)
    --> PlacementRelTo omitted : the placement is absolute in the world system.

Axis placement : defaults or explicit axes?

Is the local system aligned with the parent axes (no rotation)?
|
+-- YES --> omit BOTH Axis and RefDirection. Defaults [0,0,1] and [1,0,0] apply.
|
+-- NO  --> supply BOTH Axis and RefDirection. Supplying one only fails
            the AxisAndRefDirProvision rule.

Patterns

Pattern : Build a relative placement chain

ALWAYS give each element an IfcLocalPlacement whose PlacementRelTo points at its spatial-structure parent's placement : door to wall, wall to storey, storey to building, building to site. ALWAYS make the RelativePlacement express the offset and rotation from the parent system, not from the world. NEVER create a cycle : an element's PlacementRelTo chain MUST terminate at an absolute (parentless) placement. A cycle makes world resolution non-terminating.

Pattern : Define an axis placement

ALWAYS use an IfcAxis2Placement3D for a 3D RelativePlacement and an IfcAxis2Placement2D for a 2D one ; WR21 rejects a dimension mismatch with the parent. ALWAYS omit both Axis and RefDirection when the local system is axis-aligned with the parent : the defaults [0,0,1] and [1,0,0] apply and the file stays compact. NEVER supply only one of Axis and RefDirection : AxisAndRefDirProvision requires both or neither. NEVER set Axis and RefDirection parallel : AxisToRefDirPosition requires a non-zero cross product.

Pattern : Place an element on a grid

ALWAYS model a grid-positioned element with an IfcGridPlacement whose PlacementLocation is an IfcVirtualGridIntersection referencing exactly two IfcGridAxis instances. ALWAYS use OffsetDistances to shift the element off the exact axis intersection rather than inventing a separate point. NEVER reference the same IfcGridAxis twice in IntersectingAxes : the list is UNIQUE and two axes are required to define an intersection.

Pattern : Resolve a product to world coordinates

ALWAYS resolve a world position by composing every RelativePlacement transform from the element up the PlacementRelTo chain to the parentless root. ALWAYS treat a placement with no PlacementRelTo as absolute : it is already in the world coordinate system. NEVER assume an element is at the world origin because its RelativePlacement origin is (0,0,0) : (0,0,0) is relative to the parent, and the parent chain supplies the real offset.

Pattern : Honour the version differences

ALWAYS read PlacementRelTo from IfcLocalPlacement itself in IFC2x3 and IFC4, and from the IfcObjectPlacement supertype in IFC4.3 : the attribute moved up the hierarchy, but it exists in every version. NEVER write IfcLinearPlacement or IfcAxis2PlacementLinear in an IFC2x3 or IFC4 file : both are IFC4.3 additions and do not exist in the earlier schemas.

Reference Links

  • references/methods.md : the complete verified entity definitions for IfcObjectPlacement, IfcLocalPlacement, IfcPlacement, IfcAxis2Placement3D, IfcAxis2Placement2D, IfcCartesianPoint, IfcDirection, IfcGridPlacement, IfcVirtualGridIntersection, the IfcAxis2Placement and IfcGridPlacementDirectionSelect selects, and the per-version difference matrix.
  • references/examples.md : worked STEP scenarios : an absolute site placement, a four-level placement chain, a rotated axis placement, a grid placement, and reading a product to world coordinates.
  • references/anti-patterns.md : the placement failure modes this skill prevents, each with the reason it fails.

Official sources

Related skills

  • ifc-syntax-geometry-representations : IfcShapeRepresentation, IfcGrid, and the representation context whose WorldCoordinateSystem defines the project origin.
  • ifc-syntax-georeferencing : IfcMapConversion, IfcProjectedCRS, the IfcSite reference latitude/longitude, and IFC4.3 IfcLinearPlacement.
  • ifc-impl-geometry-extraction : the workflow for reading geometry and resolving world coordinates in practice.