| name | ifc-errors-geometry-issues |
| description | Use when an IFC model loads blank in a viewer, geometry is missing, garbled, off-scale, mispositioned, or silently dropped on import, or a buildingSMART validation report flags a GEM rule. Prevents shipping shape representations with no representation context, placement chains that mix 2D and 3D, non-watertight Breps, degenerate or duplicated geometry, and geometry that the declared MVD forbids. Covers GEM051 and GEM052 missing or wrong context, IfcLocalPlacement chain errors and dimension mismatch, IfcFacetedBrep watertight-shell rules, GEM111, GEM112 and GEM113 duplicated and colinear points, zero-area faces and non-manifold solids, and MVD geometry mismatch across IFC2x3, IFC4 and IFC4.3. Keywords: IFC geometry error, nothing shows in viewer, blank model, empty model, model off by 1000x, geometry dropped on import, GEM051, GEM052, GEM111, GEM112, GEM113, representation context missing, IfcGeometricRepresentationContext, invalid placement chain, non-watertight shell, non-manifold solid, zero-area face, degenerate geometry, Brep not closed, MVD geometry mismatch, "why is my IFC empty", "geometry looks wrong", "where did my walls go", how do I fix invalid IFC geometry, what makes IFC geometry invalid.
|
| license | MIT |
| compatibility | Designed for Claude Code. Requires IFC IFC2x3, IFC4, IFC4.3. |
| metadata | {"author":"OpenAEC-Foundation","version":"1.0"} |
IFC Geometry Issues
Diagnose and fix the five geometry fault classes that make an IFC model load
blank, render garbled, sit in the wrong place, or get dropped on import :
missing representation context, broken placement chains, malformed Brep,
degenerate or duplicated geometry, and geometry that contradicts the declared
Model View Definition (MVD).
A geometry fault is rarely a STEP syntax error. The file parses, the schema
check often passes, yet the viewer shows nothing. The fault lives in the
geometry graph : a representation with no context, a placement that resolves
nowhere, a shell that is not closed.
For the geometry framework itself (how IfcProductDefinitionShape,
IfcShapeRepresentation and contexts fit together) see
ifc-syntax-geometry-representations. For Brep, CSG and clipping construction
see ifc-syntax-geometry-brep. For what each MVD permits see ifc-core-mvd.
For EXPRESS WHERE-rule and abstract-instantiation errors see
ifc-errors-schema-validation. Full entity signatures are in
references/methods.md ; STEP snippets in references/examples.md ; the
failure catalog in references/anti-patterns.md.
Quick Reference
Symptom to cause map
| Symptom | Fault class | GEM rule | Section |
|---|
| Viewer is blank, no geometry at all | Missing representation context | GEM051 | Tree A, Pattern 1 |
| Some elements invisible, sub-views broken | Wrong or missing sub-context | GEM052 | Pattern 1 |
| Element rendered at origin or far away | Broken placement chain | OJP family | Tree B, Pattern 2 |
| Whole model off by 1000x | Unit declaration mismatch (out of scope) | n/a | Tree B note |
| Solid looks hollow, leaks, or fails boolean | Non-watertight Brep | GEM001 | Tree A, Pattern 3 |
| Element silently disappears, engine crash | Degenerate geometry | GEM111/112/113 | Tree A, Pattern 4 |
| Geometry valid but dropped on import | MVD geometry mismatch | n/a | Tree C, Pattern 5 |
The five fault classes
- Missing representation context : shape representations exist but no
IfcGeometricRepresentationContext is present or correctly referenced.
- Broken placement chain :
IfcLocalPlacement.PlacementRelTo points
nowhere, forms a cycle, or mixes 2D and 3D placements.
- Malformed Brep : an
IfcClosedShell that is not watertight, or
Cartesian points referenced by fewer than three poly-loops.
- Degenerate or duplicated geometry : duplicated points in a poly-loop,
colinear points defining an arc, zero-area faces, non-manifold solids.
- MVD geometry mismatch : the geometry type used is forbidden by the MVD
named in the STEP
FILE_DESCRIPTION header.
Core rules
- ALWAYS give a project that carries geometry exactly one
IfcGeometricRepresentationContext with ContextType = 'Model' and
CoordinateSpaceDimension = 3. NEVER ship IfcShapeRepresentation instances
whose ContextOfItems resolves to nothing (GEM051).
- ALWAYS place
'Body' geometry in an IfcGeometricRepresentationSubContext
whose ParentContext is the Model context. NEVER invent sub-context
identifiers outside the standard set (GEM052).
- ALWAYS terminate every
IfcLocalPlacement.PlacementRelTo chain at a
placement with PlacementRelTo = $ (absolute, in world coordinates). NEVER
let a 3D placement reference a 2D parent placement.
- ALWAYS make an
IfcFacetedBrep watertight : every edge used by exactly two
faces, every IfcCartesianPoint referenced by at least three IfcPolyLoop
instances. NEVER leave a hole in an IfcClosedShell.
- NEVER repeat a point inside one
IfcPolyLoop or one IfcPolygonalFaceSet
face (GEM111), nor inside one indexed poly-curve (GEM112). NEVER define an
arc segment of an IfcIndexedPolyCurve with colinear points (GEM113).
- ALWAYS match the geometry type to the MVD declared in the header. NEVER put
IfcBooleanClippingResult or parametric geometry in a Reference View file.
Decision Trees
Tree A : "Nothing shows in the viewer"
The model loads but no geometry renders.
|
+-- Do the elements have a Representation at all?
| IfcProduct.Representation is $ on every element.
| -> The elements are geometry-less. This is a SEMANTIC gap, not a
| geometry error. Author IfcProductDefinitionShape. STOP.
|
+-- Is there an IfcGeometricRepresentationContext in the file?
| No context instance exists.
| -> Fault class 1. Add one Model context. See Pattern 1. (GEM051)
|
+-- Does each IfcShapeRepresentation.ContextOfItems resolve to a real
| context instance?
| The #id points at a deleted or wrong-typed entity.
| -> Fault class 1. Repair ContextOfItems. See Pattern 1. (GEM051)
|
+-- Does the geometry use IfcFacetedBrep or IfcClosedShell?
| Yes, and the viewer shows partial or no solids.
| -> Suspect a non-watertight shell. Go to Pattern 3. (GEM001)
|
+-- Are elements dropped one by one rather than all at once?
-> Suspect degenerate geometry per element. Go to Pattern 4.
(GEM111/112/113)
Tree B : "Geometry is the wrong size or in the wrong place"
Geometry renders but is mispositioned or mis-scaled.
|
+-- Is the WHOLE model uniformly off by 1000x (or 0.001x)?
| -> Unit declaration mismatch : IfcUnitAssignment declares metres while
| coordinates are millimetres (or the reverse). This is a UNIT fault,
| NOT a geometry fault, and is out of scope for this skill. Verify the
| IfcProject IfcUnitAssignment length unit against the coordinate
| magnitudes. STOP.
|
+-- Is ONE element (or a group) at the project origin when it should be
| elsewhere?
| -> Broken placement chain. IfcLocalPlacement.PlacementRelTo is $ when it
| should reference a parent, or RelativePlacement is the identity.
| Go to Pattern 2.
|
+-- Is ONE element far from the model, at extreme coordinates?
| -> Either a placement references the wrong parent, or geometry items
| carry absolute world coordinates instead of local ones. Go to
| Pattern 2.
|
+-- Does the schema check report a dimension error on a placement?
-> A 3D IfcLocalPlacement references a 2D parent, or an
IfcAxis2Placement dimension does not match its context
CoordinateSpaceDimension. Go to Pattern 2.
Tree C : "Geometry was valid but the importer dropped it"
The file passes the schema check, the geometry is well formed, yet the
receiving tool shows nothing or imports flat boxes.
|
+-- Read the ViewDefinition in the STEP FILE_DESCRIPTION header.
|
+-- Header says ReferenceView, but the file contains IfcBooleanResult,
| IfcBooleanClippingResult, IfcHalfSpaceSolid, or CSG geometry.
| -> MVD mismatch. Reference View forbids CSG and clipping. The importer
| drops what the MVD does not cover. Go to Pattern 5.
|
+-- Header says ReferenceView, but the file contains parametric
| dimension-driven geometry beyond simple swept solids.
| -> MVD mismatch. Reference View permits tessellation and simple swept
| solids only. Go to Pattern 5.
|
+-- Header MVD requires a representation the file does not provide (a
| Coordination View profile that mandates Brep, file ships only an axis).
-> MVD mismatch in the other direction : required geometry absent. Go
to Pattern 5.
Patterns
Pattern 1 : Every shape representation needs a resolvable context
IfcShapeRepresentation.ContextOfItems MUST resolve to a real
IfcGeometricRepresentationContext (or one of its sub-contexts). Gherkin rule
GEM051 ("presence of geometric context") fails when no context exists ;
GEM052 ("correct geometric subcontexts") fails when sub-contexts are
missing or malformed.
- A project carrying geometry MUST hold exactly one
IfcGeometricRepresentationContext with ContextType = 'Model' and
CoordinateSpaceDimension = 3. A 2D 'Plan' context is optional.
- The context is reached from the project :
IfcProject.RepresentationContexts
lists every top-level context. A context absent from that list is invisible
to consumers even if it exists as an instance.
'Body' solid geometry belongs in an IfcGeometricRepresentationSubContext
with ParentContext set to the Model context and TargetView = MODEL_VIEW.- The sub-context inherits
WorldCoordinateSystem, CoordinateSpaceDimension,
Precision and TrueNorth from its parent. In STEP these inherited slots
are encoded as * (derived).
See references/examples.md Example 1 for the correct context skeleton and
the GEM051 failure case.
Pattern 2 : Valid placement chains
Every IfcProduct carries ObjectPlacement, almost always an
IfcLocalPlacement. The chain MUST be sound :
RelativePlacement is required and gives the transform into the parent
coordinate system. PlacementRelTo is optional : present means relative to
another placement, $ means absolute in world coordinates.- ALWAYS terminate the chain. A typical chain is door to wall to storey to
building to site, with the site placement holding
PlacementRelTo = $.
- NEVER form a cycle : placement A relative to B relative to A makes world
resolution non-terminating.
- A 3D
IfcLocalPlacement MUST reference a 3D parent. Mixing a 3D placement
with a 2D IfcAxis2Placement parent is a dimension mismatch the schema
rejects.
- Geometry
Items inside an IfcShapeRepresentation are in the element LOCAL
coordinate system. NEVER bake world coordinates into the geometry while ALSO
applying a non-identity placement : the offsets add up and the element flies
away from the model.
See references/examples.md Example 2.
Pattern 3 : Watertight Brep
An IfcFacetedBrep has a single attribute Outer, an IfcClosedShell. A
closed shell is watertight : its faces fully enclose a volume.
- Every edge MUST be shared by exactly two faces. An edge used once leaves a
hole ; an edge used three or more times is non-manifold.
- Per the IFC informal propositions on
IfcFacetedBrep : all bounding loops
of all faces MUST be IfcPolyLoop, and each IfcCartesianPoint MUST be
referenced by at least three poly-loops bounding different faces.
- A point referenced by only one or two poly-loops marks an open shell : the
solid is not closed at that vertex.
- Gherkin rule GEM001 ("closed-shell-edge-usage") checks the edge-usage
invariant. A failure means the shell is not a valid solid boundary.
IfcFaceOuterBound designates the outer loop of a face ; interior holes use
IfcFaceBound. NEVER give a face two outer bounds.
See references/examples.md Example 3 and references/anti-patterns.md
AP-3 for the missing-face failure.
Pattern 4 : No degenerate or duplicated geometry
Degenerate geometry is geometry that collapses : zero length, zero area, zero
volume, or topology that cannot describe a solid. The geometry engine either
crashes or silently drops the element.
- GEM111 : NEVER repeat a point inside one
IfcPolyLoop, one polyline, or
one IfcPolygonalFaceSet face. Adjacent identical points create a
zero-length edge and a zero-area face.
- GEM112 : NEVER repeat a point inside one
IfcIndexedPolyCurve.
- GEM113 : NEVER define an arc segment of an
IfcIndexedPolyCurve with
three colinear points : an arc through colinear points is undefined.
- NEVER author a profile with zero extent : an
IfcRectangleProfileDef with
XDim = 0, an IfcCircleProfileDef with Radius = 0.
- NEVER extrude with
Depth = 0 or revolve with Angle = 0 : the result is a
zero-volume solid. IfcExtrudedAreaSolid.Depth is an
IfcPositiveLengthMeasure, so 0. violates the type.
- For tessellation, NEVER emit a triangle in
IfcTriangulatedFaceSet.CoordIndex
whose three indices are not all distinct : a repeated index is a zero-area
triangle.
See references/examples.md Example 4 and references/anti-patterns.md
AP-4 through AP-6.
Pattern 5 : Match geometry to the declared MVD
The STEP FILE_DESCRIPTION header carries the ViewDefinition string naming
the MVD. The geometry in the file MUST stay inside what that MVD permits, or
conforming importers drop it.
| MVD | IFC version | Geometry permitted |
|---|
| Coordination View 2.0 | IFC2x3 | SweptSolid, Clipping, Brep, MappedRepresentation |
| Reference View | IFC4, IFC4.3 | Tessellation, simple swept solids, swept disk solids |
| Design Transfer View | IFC4 | Reference View superset plus full swept, CSG, Clipping, Brep |
- The Reference View EXCLUDES CSG and Boolean clipping : NEVER put
IfcBooleanResult, IfcBooleanClippingResult or IfcHalfSpaceSolid in a
file whose header declares Reference View.
- The Reference View EXCLUDES parametric dimension-driven geometry beyond
simple swept solids.
- The Design Transfer View is a true superset of the Reference View : any
Design Transfer View importer also reads Reference View data, but NOT the
reverse.
- A geometry-MVD mismatch is NOT a schema error. The schema check passes ; the
importer simply ignores geometry the MVD does not name. Diagnose by reading
the header, then the representation types actually used.
See references/examples.md Example 5 and references/methods.md for the
header format and the per-MVD geometry tables.
Version Notes
IfcFacetedBrep, IfcClosedShell, IfcPolyLoop, IfcExtrudedAreaSolid,
IfcLocalPlacement and IfcGeometricRepresentationContext exist in IFC2x3,
IFC4 and IFC4.3 with stable geometry semantics.- Tessellation (
IfcTriangulatedFaceSet, IfcPolygonalFaceSet,
IfcCartesianPointList3D) was introduced in IFC4. IFC2x3 has no
tessellation : in IFC2x3, faceted geometry uses IfcFacetedBrep or surface
models, so GEM rules about tessellated face sets do NOT apply to IFC2x3.
- The Reference View and Design Transfer View are IFC4 and IFC4.3 MVDs.
IFC2x3 uses Coordination View 2.0. Apply the MVD geometry table for the
matching version only.
- GEM rule codes are buildingSMART Gherkin normative rules and apply to
IFC4 and IFC4.3 validation ; the underlying geometry invariants (watertight
shells, no duplicated points) hold for IFC2x3 geometry as well.
Reference Links
references/methods.md : entity and attribute signatures for the geometry
entities, the GEM rule reference table, the STEP header format.references/examples.md : verified STEP snippets, broken and fixed, for each
of the five fault classes.references/anti-patterns.md : the failure catalog with root cause and fix.
Official sources (see SOURCES.md) :
