Geometry Kernel

ArchAI v1 uses a practical 2D / 2.5D geometry kernel. The kernel exists to make agent planning deterministic for land, envelopes, and early building options. It is not a full solid-modeling kernel.

Decision

@archai/geometry is the only geometry API used by higher-level packages. Third-party kernels sit behind narrow adapters so the graph, operation model, eval engine, and docs do not depend on vendor-specific shapes.

Capability	Decision	Used For
Polygon clipping, booleans, offsets	Clipper2 through a pinned WASM/native adapter	setbacks, envelope clipping, buildable regions, floorplate clipping, wall offsets
Pure JavaScript boolean fallback	`polygon-clipping`	dev/test fallback when WASM is unavailable
Preview triangulation	`earcut`	glTF, Blender, browser preview meshes
Terrain TIN	`delaunator`	sampled survey/terrain points and slope sampling
Spatial index	`rbush`	affected-region evals, adjacency candidates, collision prefilters
CRS transforms	`proj4`	declared CRS import/export transforms

Clipper2 is the primary polygon engine because architecture planning needs offsetting, not just polygon booleans. Setbacks, wall offsets, road buffers, easements, and envelope repairs all depend on offset behavior.

Kernel Boundary

Application code should call ArchAI geometry functions, not third-party libraries directly.

import { offsetRegion, intersectRegions, triangulatePreview } from "@archai/geometry";

const setbackRegion = offsetRegion(parcel.boundary, {
  distance: "-5000mm",
  join: "miter",
  tolerance: "5mm"
});

const buildable = intersectRegions([parcel.region, setbackRegion, zoning.heightPlaneFootprint]);
const preview = triangulatePreview(buildable);

This keeps eval behavior stable if a low-level implementation changes.

Numeric Model

Topology-critical planar operations use normalized local coordinates and integer millimeters.

Rules:

Compute in a local projected coordinate space, not longitude/latitude.
Convert source coordinates before topology operations.
Range-check integer coordinates before calling polygon kernels.
Snap only through explicit tolerance policies.
Preserve imported source geometry as provenance when cleanup changes it.
Use bounding-box indexes as prefilters only.
Let exact geometry tests decide validity.

Canonical polygons are closed, simple, non-self-intersecting, and orientation-normalized. Outer loops are counter-clockwise; holes are clockwise.

Terrain

Terrain is 2.5D in v1: x/y topology with elevation values.

delaunator is good enough for:

sampled survey points
contours converted to sampled points
coarse slope and aspect calculations
terrain previews
grading estimates with clear tolerance warnings

It is not a constrained triangulation engine. Breaklines in v1 must be densified and validated as an approximation, or deferred to a later constrained terrain kernel.

Preview Meshes

earcut is preview-only. It is fast and small, but validity must not depend on it.

The valid flow is:

canonical polygon -> Clipper2 validity/cleanup -> ArchAI evals -> earcut preview mesh

Do not use preview triangulation to decide whether a parcel, envelope, or floorplate is valid.

Deferred

Do not implement these in v1:

full 3D BRep
3D boolean operations
NURBS
high-resolution point clouds
exact constrained terrain triangulation
native BIM geometry editing

Those should arrive as separate geometry modules after the local site-to-building loop works.