ifc-errors-geometry-issues

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

1. Missing representation context : shape representations exist but no IfcGeometricRepresentationContext is present or correctly referenced.
2. Broken placement chain : IfcLocalPlacement.PlacementRelTo points nowhere, forms a cycle, or mixes 2D and 3D placements.
3. Malformed Brep : an IfcClosedShell that is not watertight, or Cartesian points referenced by fewer than three poly-loops.
4. Degenerate or duplicated geometry : duplicated points in a poly-loop, colinear points defining an arc, zero-area faces, non-manifold solids.
5. 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) :

• IFC 4.3 specification : https://ifc43-docs.standards.buildingsmart.org/
• IFC Gherkin normative rules : https://github.com/buildingSMART/ifc-gherkin-rules
• buildingSMART validation service : https://validate.buildingsmart.org/
• IFC4 Reference View MVD : https://standards.buildingsmart.org/MVD/RELEASE/IFC4/ADD2_TC1/RV1_2/HTML/schema/views/reference-view/index.htm
• MVD database : https://technical.buildingsmart.org/standards/ifc/mvd/mvd-database/