Use when you need to attach geometry to an IFC product, read a model's shape data, or debug why a representation is rejected : the product-to-shape chain, IfcShapeRepresentation, the RepresentationIdentifier and RepresentationType value tables, the Model representation context and its sub-contexts, topology representations, named shape aspects, and mapped (instanced) geometry. Prevents a shape representation with no placement, a non-shape-model entity inside IfcProductDefinitionShape, a missing or mismatched RepresentationType, a sub-context with literal instead of derived attributes, and a self-referential mapped item. Covers IfcProduct.Representation, IfcProductRepresentation, IfcProductDefinitionShape, IfcShapeRepresentation, IfcTopologyRepresentation, IfcGeometricRepresentationContext, IfcGeometricRepresentationSubContext, IfcGeometricProjectionEnum, IfcShapeAspect, IfcRepresentationMap, IfcMappedItem, IfcCartesianTransformationOperator, IfcRepresentationItem, and IFC2x3 / IFC4 / IFC4.3 version difference
Use when you need to attach geometry to an IFC product, read a model's shape data, or debug why a representation is rejected : the product-to-shape chain, IfcShapeRepresentation, the RepresentationIdentifier and RepresentationType value tables, the Model representation context and its sub-contexts, topology representations, named shape aspects, and mapped (instanced) geometry. Prevents a shape representation with no placement, a non-shape-model entity inside IfcProductDefinitionShape, a missing or mismatched RepresentationType, a sub-context with literal instead of derived attributes, and a self-referential mapped item. Covers IfcProduct.Representation, IfcProductRepresentation, IfcProductDefinitionShape, IfcShapeRepresentation, IfcTopologyRepresentation, IfcGeometricRepresentationContext, IfcGeometricRepresentationSubContext, IfcGeometricProjectionEnum, IfcShapeAspect, IfcRepresentationMap, IfcMappedItem, IfcCartesianTransformationOperator, IfcRepresentationItem, and IFC2x3 / IFC4 / IFC4.3 version differences. Keywords: IFC geometry, IfcShapeRepresentation, IfcProductDefinitionShape, RepresentationIdentifier, RepresentationType, Body, SweptSolid, MappedRepresentation, IfcGeometricRepresentationContext, Model context, sub-context, TargetView, IfcGeometricProjectionEnum, IfcMappedItem, IfcRepresentationMap, geometry reuse, instancing, IfcShapeAspect, IfcTopologyRepresentation, how do I add geometry to an element, my geometry does not show, nothing renders in the viewer, shape representation rejected, schema validation error on representation, where is the 3D body, 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 : Geometry Representations
IFC separates what an object is (semantics : IfcWall, IfcBeam, IfcDoor)
from what it looks like (geometry). The bridge is the representation
framework : a layered chain every shape-bearing product walks, plus the context
entities that fix the coordinate frame. This skill owns the framework and the
wiring. The individual geometry primitives (extrusions, Breps, tessellation) live
in their own dedicated skills.
Applies to IFC2x3, IFC4, and IFC4.3. The core framework entities are
version-stable ; the value tables grew across versions. See Version Differences.
Quick Reference
The product-to-shape chain
Every shape-bearing product resolves its geometry down a fixed chain :
IfcProduct.Representation
-> IfcProductDefinitionShape (a kind of IfcProductRepresentation)
.Representations LIST OF
-> IfcShapeRepresentation (or IfcTopologyRepresentation)
.Items SET OF
-> IfcRepresentationItem (the actual geometry primitives)
ALWAYS walk this exact chain when reading or writing geometry. The semantics
(IfcWall) and the geometry (IfcExtrudedAreaSolid) meet only here.
IfcProduct : placement plus representation
IfcProduct is the abstract supertype of every object with a geometric or spatial
context. Two attributes matter here :
ObjectPlacement : OPTIONAL IfcObjectPlacement. The object coordinate system.
Representation : OPTIONAL IfcProductRepresentation. For a shape-bearing
product this is always its subtype IfcProductDefinitionShape.
The WHERE rule PlacementForShapeRepresentation : if Representation is an
IfcProductDefinitionShape, then ObjectPlacement MUST also be given. Geometry
items are defined in a local coordinate system ; the placement positions that
system in the world.
ALWAYS supply an ObjectPlacement whenever a shape representation is present.
NEVER leave ObjectPlacement as $ on a product that carries geometry : the file
is schema-invalid. See ifc-syntax-geometry-placement.
IfcProductDefinitionShape
The container for all shape information of one product. Subtype of
; inherits , , and
().
IfcProductRepresentation
Name
Description
Representations
LIST [1:?] OF IfcRepresentation
WHERE rule OnlyShapeModel : Representations MUST contain ONLY
IfcShapeRepresentation or IfcTopologyRepresentation instances (the two
subtypes of IfcShapeModel). Nothing else is permitted.
Inverse ShapeOfProduct : SET [1:?] OF IfcProduct (cardinality 1:N from
IFC4 : one shape definition may be shared by several products).
Inverse HasShapeAspects : SET [0:?] OF IfcShapeAspect.
IfcShapeRepresentation : the workhorse
One geometric representation of a product in one context. Supertype chain
IfcRepresentation -> IfcShapeModel -> IfcShapeRepresentation. Four attributes
(all inherited from IfcRepresentation) :
ContextOfItems : IfcRepresentationContext (required ; in practice an
IfcGeometricRepresentationContext or one of its sub-contexts).
RepresentationIdentifier : OPTIONAL IfcLabel. The kind of representation.
RepresentationType : OPTIONAL IfcLabel. The geometry/topology type.
Items : SET [1:?] OF IfcRepresentationItem. The geometric primitives.
Five WHERE rules :
CorrectContext : ContextOfItems MUST be an IfcGeometricRepresentationContext.
CorrectItemsForType : Items MUST comply with RepresentationType.
HasRepresentationIdentifier : RepresentationIdentifier MUST be present.
HasRepresentationType : RepresentationType MUST be present.
NoTopologicalItem : no topological item in Items, except IfcVertexPoint,
IfcEdgeCurve, IfcFaceSurface.
Rules 3 and 4 make RepresentationIdentifier and RepresentationType effectively
mandatory even though they are schema-level OPTIONAL. ALWAYS populate both.
RepresentationIdentifier : the kind (most common values)
Body (3D solid/surface/wireframe), Axis (2D/3D axis line), FootPrint (2D
ground projection), Box (bounding box), Profile (3D planar profile outline),
Surface (analytical surface), Reference (3D non-Body geometry), CoG (centre
of gravity point), Clearance (clearance volume), Annotation (2D/3D annotation).
IFC4.3 adds Body-FallBack and Lighting. The full verified table is in
references/methods.md. The usual identifier for a building element is Body.
RepresentationType : the geometry type (most common values)
SweptSolid (extruded/revolved area solids), AdvancedSweptSolid (tapered sweeps
along a directrix), Brep (faceted boundary representations), AdvancedBrep
(b-spline surface Breps), CSG (Boolean results), Clipping (Boolean differences
with half-spaces), Tessellation (tessellated face sets), MappedRepresentation
(mapped item references), Curve2D / Curve3D (axis curves), BoundingBox,
SurfaceModel. The full verified table is in references/methods.md.
CorrectItemsForType couples this label to Items : SweptSolid may hold ONLY
swept area solids, Tessellation ONLY tessellated face sets. The label and the
geometry kind MUST agree.
Representation contexts
Geometric items are meaningless without a context : the frame fixing the
dimension, precision, world origin, and true north.
IfcGeometricRepresentationContext is the root frame. Key attributes :
CoordinateSpaceDimension (2 or 3), Precision (OPTIONAL IfcReal, typically
1E-5), WorldCoordinateSystem (IfcAxis2Placement), TrueNorth (OPTIONAL IfcDirection). Inherited : ContextIdentifier, ContextType ('Model',
'Plan', 'NotDefined'). A project with 3D geometry MUST declare one context
with ContextType = 'Model'.
IfcGeometricRepresentationSubContext is a subtype that targets a specific view.
Explicit attributes : ParentContext (required), TargetScale (OPTIONAL),
TargetView (IfcGeometricProjectionEnum, required), UserDefinedTargetView
(OPTIONAL). Its WorldCoordinateSystem, CoordinateSpaceDimension, TrueNorth,
and Precision are DERIVED from the parent.
In a STEP file the four derived attributes appear as the asterisk * placeholder,
NEVER as repeated literal values. WHERE rules : NoCoordOperation (a sub-context
carries no coordinate operation), ParentNoSub (the parent is a plain context,
one level deep only), UserTargetProvided (UserDefinedTargetView required when
TargetView = USERDEFINED).
IfcGeometricProjectionEnum has nine values : MODEL_VIEW, PLAN_VIEW,
GRAPH_VIEW, ELEVATION_VIEW, SECTION_VIEW, REFLECTED_PLAN_VIEW,
SKETCH_VIEW, USERDEFINED, NOTDEFINED. A Body representation uses a
sub-context with TargetView = MODEL_VIEW ; an Axis uses GRAPH_VIEW ; a
FootPrint uses PLAN_VIEW.
IfcTopologyRepresentation
The sibling of IfcShapeRepresentation (both subtype IfcShapeModel). It carries
topological structure (vertices, edges, paths, faces, shells), potentially without
coordinate geometry. Same four attributes. Permitted RepresentationType values :
Vertex, Edge, Path, Face, Shell, Undefined. Rare in normal building
exchange ; used mainly in analysis and structural-connectivity models.
IfcShapeAspect
Names an addressable sub-feature of a product's geometry (one material layer of a
wall, one panel of a curtain wall). Attributes : ShapeRepresentations (LIST [1:?] OF IfcShapeModel), Name, Description, ProductDefinitional
(IfcLogical), PartOfProductDefinitionShape (the owning
IfcProductDefinitionShape or IfcRepresentationMap).
Mapped representations : geometry reuse
One geometric definition reused under many transformations, the IFC equivalent of
a CAD block. Two entities collaborate :
IfcRepresentationMap : the base definition. Attributes : MappingOrigin
(IfcAxis2Placement), MappedRepresentation (IfcRepresentation). WHERE rule
ApplicableMappedRepr : only an IfcShapeRepresentation or
IfcTopologyRepresentation is permitted as MappedRepresentation.
IfcMappedItem : the inserted instance. It IS an IfcRepresentationItem, so it
sits directly in an Items set. Attributes : MappingSource
(IfcRepresentationMap), MappingTarget (IfcCartesianTransformationOperator).
An IfcShapeRepresentation whose Items are IfcMappedItem instances uses
RepresentationType = 'MappedRepresentation'. Typed product families
(IfcDoorType, IfcFurnitureType) carry geometry once on the type and instance
it per occurrence, shrinking file size for repetitive elements.
Version differences (compact)
Item
IFC2x3
IFC4
IFC4.3
Core framework entities
present
present
present
ShapeOfProduct cardinality
1:1
1:? (shared shapes)
1:?
RepresentationIdentifier / Type tables
smaller
larger
largest
Body-FallBack, Lighting identifiers
absent
absent
present
PointCloud representation type
present
present
DEPRECATED, use Point
HasCoordinateOperation inverse (georeferencing)
absent
present
present
Decision Trees
Does my product need a representation, a placement, or both?
Is the product physically located and shape-bearing?
|
+-- It carries geometry
| --> give it an IfcProductDefinitionShape AND an IfcObjectPlacement.
| Both are required together (PlacementForShapeRepresentation rule).
|
+-- It is located but has no own geometry (e.g. a spatial zone)
| --> give it an IfcObjectPlacement, leave Representation as $.
|
+-- It is an abstract grouping product
--> leave both as $.
Which RepresentationIdentifier?
What does this representation depict?
|
+-- The 3D solid / surface body of the element --> Body
+-- A 2D or 3D axis line (wall axis, beam axis) --> Axis
+-- A 2D ground-level outline --> FootPrint
+-- A simplified bounding box --> Box
+-- A 3D planar profile outline (door, window) --> Profile
+-- An analytical surface --> Surface
+-- 3D geometry not part of Body (opening ref) --> Reference
+-- A centre-of-gravity point --> CoG
+-- A clearance volume --> Clearance
+-- A 2D or 3D annotation --> Annotation
Does the data carry coordinate geometry (points, curves, solids)?
|
+-- YES --> IfcShapeRepresentation. The normal case for building geometry.
|
+-- NO, it is pure topological structure (connectivity, no coordinates)
--> IfcTopologyRepresentation. Rare ; analysis / structural models.
Should I reuse geometry across many elements?
Is the same geometry repeated for many occurrences (doors, furniture, fixtures)?
|
+-- YES --> define it once in an IfcRepresentationMap, instance each occurrence
| with an IfcMappedItem ; RepresentationType = 'MappedRepresentation'.
|
+-- NO --> give each element its own IfcShapeRepresentation with concrete items.
Patterns
Pattern : Wire a Body representation into the Model context
ALWAYS build the chain bottom-up : create the geometry items, wrap them in an
IfcShapeRepresentation whose ContextOfItems is the Body sub-context,
RepresentationIdentifier is 'Body', and RepresentationType matches the
geometry ('SweptSolid' for an extrusion). Put that representation in an
IfcProductDefinitionShape.Representations list, point the product's
Representation at it, and give the product an ObjectPlacement.
NEVER omit the placement : the PlacementForShapeRepresentation rule rejects a
shape representation with no placement.
See references/examples.md for the full worked STEP file.
Pattern : Declare the Model context and its sub-contexts
ALWAYS declare exactly one IfcGeometricRepresentationContext with
ContextType = 'Model' and CoordinateSpaceDimension = 3 for a 3D model. Add one
IfcGeometricRepresentationSubContext per representation kind, each pairing a
RepresentationIdentifier with a TargetView.
ALWAYS write the four derived sub-context attributes as the * placeholder in the
STEP file. NEVER copy the parent's WorldCoordinateSystem, dimension, precision,
or true north as literal values into a sub-context.
NEVER nest a sub-context under another sub-context : the ParentNoSub rule allows
exactly one level.
Pattern : Carry multiple representations on one product
ALWAYS place every representation of a product (Body, Axis, FootPrint, Box)
as a separate IfcShapeRepresentation in the single
IfcProductDefinitionShape.Representations list, each tied to its own
identifier-and-view sub-context. They are complementary views.
NEVER treat multiple representations as conflicting duplicates : a wall legitimately
has a Body solid and an Axis line at the same time.
Pattern : Instance geometry with a mapped representation
ALWAYS define repeated geometry once as an IfcRepresentationMap whose
MappedRepresentation is an IfcShapeRepresentation, and instance it per
occurrence with an IfcMappedItem whose MappingSource is that map and whose
MappingTarget is an IfcCartesianTransformationOperator.
ALWAYS set the consuming representation's RepresentationType to
'MappedRepresentation' when its Items are IfcMappedItem instances.
NEVER let an IfcMappedItem map a representation that transitively contains the
item itself : that infinite recursion is forbidden.
Pattern : Name a sub-feature with IfcShapeAspect
ALWAYS use IfcShapeAspect to give a name to a distinct geometric part (a material
layer, a curtain-wall panel, a named connection zone). Set ShapeRepresentations
to the shape models forming the aspect and PartOfProductDefinitionShape to the
owning IfcProductDefinitionShape or IfcRepresentationMap.
Pattern : Honour the version differences
ALWAYS treat the core framework entities as version-stable across IFC2x3, IFC4,
and IFC4.3.
ALWAYS allow one IfcProductDefinitionShape to be shared by several products in
IFC4 and IFC4.3 (ShapeOfProduct is 1:N) ; in IFC2x3 the relation is 1:1.
ALWAYS draw RepresentationIdentifier and RepresentationType values from the
table of the target version : Body-FallBack and Lighting are IFC4.3
identifiers, and PointCloud is deprecated in IFC4.3 in favour of Point.
Reference Links
references/methods.md : the complete verified entity definitions, the full
RepresentationIdentifier and RepresentationType value tables, the context
entities with their derived attributes and WHERE rules, the
IfcCartesianTransformationOperator family, and the per-version difference
matrix.
references/examples.md : worked STEP scenarios : a Body representation wired
into the Model context, a product carrying both Body and Axis, a mapped
representation instancing a door, and a named shape aspect.
references/anti-patterns.md : the failure modes this skill prevents, each with
the WHERE rule it breaks and the correct form.
