Units And Geometry Primitives

Units and geometry must be deterministic so paths, hashes, evals, and exports are reproducible.

ArchAI uses an internal coordinate-space model. GeoJSON, JSON-FG, LandXML, IFC, USD, glTF, Blender, Archicad, and Revit are adapter formats, not the internal coordinate truth.

For the full format decision, see Coordinates And Formats. For the v1 implementation decision, see Geometry Kernel.

Canonical Units

Quantity	Canonical storage
Length	millimeters
Area	square meters
Volume	cubic meters
Angle	degrees in author-facing data, radians in math internals
Time	ISO 8601 strings

Unit Helpers

mm(3000)
m(3)
deg(90)
sqm(12)

Source should avoid ambiguous unitless dimensions.

distance 5000mm
target_gfa 4200sqm
max 18000mm

Coordinate Systems

Coordinate system	Purpose
Project	Local authoring coordinates
Site	Site-relative coordinates
Survey	Survey source coordinates
GIS	Geospatial source data
Georeferenced	Real-world CRS
Local element	Element-local transforms
Backend	Host-specific coordinates

Every coordinate must belong to an explicit coordinate space or inherit one from the nearest geometry block.

boundary:
  coordinate_space site.main.frames.local
  unit mm

  edge front: (0, 0) -> (42000, 0)

Canonical JSON should prefer explicit coordinate objects:

{
  "space": "site.main.frames.local",
  "x": "0mm",
  "y": "42000mm",
  "z": "0mm"
}

Geometry Levels

Level	Purpose	Example
Semantic geometry	Agent-editable intent	wall baseline, parcel edge, floorplate boundary
Realization geometry	High-fidelity derived shape	solids, BRep, openings
Preview geometry	Fast visual output	mesh, glTF, Blender scene

Agents should edit semantic geometry first. Realization and preview geometry are derived artifacts.

Geometry Primitives

Primitive	Used by
Point	survey, terrain, boundaries
Polyline	parcel edges, contours, roads
Boundary loop	parcels, spaces, floorplates
Polygon region	envelopes, no-build zones, floorplates
Terrain surface	topo, grading, slope
Extrusion	preview walls, massing, slabs
Mesh proxy	Blender, glTF, USD previews

Kernel Rule

Semantic geometry belongs to ArchAI. Third-party kernels are implementation details behind @archai/geometry.

V1 uses local projected coordinates and integer millimeters for topology-critical planar operations. Geo-referenced coordinates are transformed into local frames before parcel, setback, envelope, and floorplate operations run.

The implementation stack is:

Capability	Kernel
Polygon clipping, booleans, offsets	Clipper2 adapter
Preview triangulation	`earcut`
Terrain TIN	`delaunator`
Spatial indexing	`rbush`
CRS transforms	`proj4`

earcut output is preview geometry only. Eval validity must come from canonical polygons and deterministic geometry checks, not from preview triangulation.