Roadmap: define planar and spatial geometry semantics for IFCDR

[BjornFidder]

Context

IFCDR 0.5 currently models line and polyline geometry with XY coordinates. The first CadDocument conversion will embed these entities at Z = 0, mapping lines to cadcodec Line and planar polylines to LwPolyline.

IFCDR needs a deliberate path to spatial geometry without mechanically duplicating every CAD entity into separate 2D and 3D concepts. DWG/DXF provide useful precedent: LINE uses 3D endpoints, lightweight polylines are planar, spatial polylines carry XYZ vertices, and circles/arcs are planar geometry placed in 3D. We should reuse sound geometric ideas while correcting legacy or format-specific quirks rather than copying them blindly.

Proposed direction

Model entities according to their geometric semantics:

• Point, line, ray, and xline can use one spatial model with XYZ coordinates; 2D instances simply have Z = 0.
• Circle, arc, ellipse, text, hatch, dimension, table, and similar planar entities should use local 2D geometry plus an explicit 3D plane or placement.
• Polyline and spline need an explicit distinction between planar and spatial geometry where their invariants and supported properties differ.
• Meshes, surfaces, and solids are inherently spatial and should receive dedicated models later.

Do not create separate logical streams only to optimize repeated zero-valued Z coordinates. A logical 3D column may later use a constant/default physical encoding. Separate streams are appropriate when entity variants have genuinely different fields or invariants, such as planar polylines with bulges versus non-planar XYZ polylines.

The public Rust model should expose semantic geometry and hide whether data came from dense, constant, chunked, or version-specific columns. This direction builds on #3, which separates logical streams from physical chunk encoding.

Logical columns and physical JSON representation

A logical IFCDR column should not be identified permanently with one physical JSON representation. The first spatial version can keep using dense arrays:

"z1": [0.0, 0.0, 0.0]

A later, explicitly versioned column-encoding extension may allow the equivalent constant representation:

"z1": {
  "encoding": "constant",
  "value": 0.0,
  "length": 3
}

Both forms represent the same logical three-value column. The stream directory and registry still declare z1 as a typed column; only its physical payload changes. An explicit logical length also supports pool columns whose length is not the entity-row count.

Validation and typed stream views should normalize over this distinction: validate the value type and logical length, then expose identical indexed values regardless of whether the payload is dense or constant. The initial 3D work does not need to implement constant columns, but the schema and Rust internals should avoid making Vec<T> part of the permanent semantic contract. Chunked and binary encodings can follow the same separation later.

Design questions

• Define Point3, vectors, bounds, planes, and placements.
• Decide how current IFCDR 0.5 XY resources are exposed as Z = 0 without breaking later spatial support.
• Define planar versus spatial polyline and spline semantics.
• Define world, scope-local, and entity-local coordinate frames.
• Map IFCDR planes and placements to DWG/DXF OCS, normals, and elevation.
• Decide how canonicalization treats explicit zero Z columns versus equivalent constant/default encodings.
• Preserve entity identity, scope membership, draw order, and drawing units across dimensional representations.
• Determine which source-format representation details belong in semantic IFCDR and which belong in IFCPR preservation data.

Expected validation scenarios

A future implementation should cover at least:

• Existing 2D line and planar polyline fixtures remain valid and produce Z = 0 geometry.
• A line with non-zero endpoint Z values survives IFCCAD -> CadDocument -> DWG/DXF -> CadDocument.
• A planar entity can be placed on a tilted plane without tessellating it into spatial primitives.
• A planar polyline maps to LwPolyline, while a non-planar polyline maps to a spatial cadcodec Polyline.
• Equivalent logical geometry remains stable across supported physical encodings.

Out of scope

• Implementing 3D geometry in the initial 2D CadDocument conversion proof.
• Designing ACIS solids, meshes, surfaces, or IFC product-geometry generation.
• Defining camera, rendering, or complete stored-view behavior beyond the coordinate information required for correct geometry.