Coordinates And Formats

ArchAI should be compatible with geospatial formats, but it should not be shaped internally like any single interchange format.

Decision

Use an internal coordinate model that is:

• Path-addressed.
• Unit-aware.
• CRS-aware.
• Frame-aware.
• Precise enough for buildings.
• Able to represent land, terrain, levels, solids, and backend mappings.

Use GeoJSON, JSON-FG, LandXML, IFC, USD, glTF, Blender, Archicad, and Revit as adapters.

ArchAI internal coordinate model
  -> GeoJSON / JSON-FG for GIS and web interchange
  -> LandXML for civil and terrain interchange
  -> IFC for BIM exchange
  -> USD / glTF / Blender for visualization and scene workflows
  -> Archicad / Revit native adapters

Why Not GeoJSON Internally?

GeoJSON is excellent for parcels, zoning overlays, roads, context layers, and web maps. It is not enough for ArchAI’s internal model because RFC 7946 GeoJSON is tied to WGS84 longitude/latitude and simple feature geometry.

ArchAI also needs:

• Millimeter-precise local building coordinates.
• Site-local and building-local frames.
• Level-local frames.
• Vertical datums.
• Terrain surfaces and derived slope regions.
• Floorplates and solids.
• Hosted BIM relationships.
• Parametric walls, slabs, openings, cores, and systems.

Use GeoJSON for interchange, not internal truth.

Coordinate Spaces

Every coordinate belongs to an explicit coordinate space.

interface CoordinateSpace {
  path: GraphPath;
  kind:
    | "geographic"
    | "projected"
    | "site_local"
    | "building_local"
    | "level_local"
    | "element_local"
    | "backend";

  crs?: {
    authority?: "EPSG" | "OGC";
    code?: string;
    wkt2?: string;
    projjson?: unknown;
  };

  parent?: GraphPath;
  axes: ["x", "y", "z"] | ["lon", "lat", "h"];
  units: ["mm", "mm", "mm"] | ["m", "m", "m"] | ["deg", "deg", "m"];
  verticalDatum?: string;
  transformToParent?: Transform;
}

Standard Coordinate Spaces

Space	Path pattern	Purpose
Geographic	site.{site}.frames.geographic	Longitude/latitude/height
Projected	site.{site}.frames.projected	CRS-backed survey/GIS meters
Site local	site.{site}.frames.local	Site design coordinates
Building local	buildings.{building}.frames.local	Building-local millimeter coordinates
Level local	buildings.{building}.levels.{level}.frame	Floor-local coordinates
Element local	buildings.{building}.elements.{group}.{element}.frame	Element-local transforms
Backend	adapters.{backend}.frames.{frame}	Host-specific coordinates

Coordinate Values

Canonical JSON should prefer explicit coordinate objects:

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

Compact tuples are allowed only when the parent block declares a coordinate space and unit:

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

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

Transforms

Transforms connect coordinate spaces.

interface Transform {
  from: GraphPath;
  to: GraphPath;
  kind: "identity" | "affine3d" | "crs_operation" | "backend_mapping";
  matrix?: number[];
  operation?: {
    authority?: "EPSG" | "PROJ" | "OGC";
    code?: string;
    pipeline?: string;
  };
  accuracy?: Quantity;
}

Format Roles

Format	Use it for	Do not use it for
GeoJSON	Parcels, zoning overlays, roads, context layers, web maps	Internal building frames, solids, hosted BIM semantics
JSON-FG	GeoJSON-like exchange with richer feature/CRS needs	Internal parametric building model
WKT-CRS	CRS definitions and coordinate operations	Geometry storage
PROJ / PROJJSON	Coordinate transformations	Architectural semantics
LandXML	Terrain and civil/survey exchange	Complete building model
IFC	BIM exchange	Fast internal authoring loop
USD	Scene composition and visualization	Legal/planning source of truth
glTF	Web preview	BIM semantics
Blender	Visual/procedural scene workflows	Authoritative BIM behavior

GeoJSON Export Profile

When exporting GeoJSON:

• Reproject to RFC 7946-compatible WGS84 longitude/latitude unless explicitly using a non-RFC profile.
• Put ArchAI paths in feature properties.
• Preserve stable IDs in feature properties.
• Use properties for semantic type and source path.
• Use foreign members only for clearly documented ArchAI metadata.

{
  "type": "Feature",
  "properties": {
    "archai:path": "site.main.parcels.pcl_001",
    "archai:id": "Parcel.PCL-001",
    "archai:kind": "parcel"
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[8.54, 47.37], [8.55, 47.37], [8.55, 47.38], [8.54, 47.37]]]
  }
}

JSON-FG Direction

JSON-FG is the preferred future path for richer feature exchange where GeoJSON is too narrow. It should be considered for:

• CRS-aware feature exchange.
• Richer feature typing.
• Feature data that must remain GeoJSON-compatible where possible.

Do not make JSON-FG the internal ArchAI graph. Treat it as an adapter profile.