48225049f5
SPEC.md §2 gained the rule in fef51e4e; the detailed cell-key spec defines the same
AltSchedule and said only that a surface-only tileset declares a band of infinite
width. It now gives the JSON form (null, read back as +inf), that the canonical
CBOR carries the float, and that NaN and -inf widths are refused.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
2.7 KiB
Map sub-spec — The 4D cell key
Normative refinement of SPEC §2. Reference: map-schema::CellKey.
A tile is addressed by four orthogonal axes. Equality is component-wise; the field order below is the canonical sort order the tileset directory MUST follow (SPEC §4).
CellKey = (s2: S2CellId, alt: AltBand, time: TimeBucket, lod: Lod)
1. Horizontal — s2: u64
An S2 cell identifier. S2 imposes a Hilbert ordering on the sphere: numerically adjacent ids are spatially adjacent, so a viewport's cells occupy a near-contiguous run of the integer key space. This is the property that makes the directory range-requestable. The S2 level (0..=30) is the horizontal LOD; a reader recovers it from the trailing-sentinel position of the id. The all-zero id is invalid.
The reference treats the id as an opaque, orderable token; the full S2 geometry
(point↔cell, neighbours, covering a viewport) lives in map-index (ported from
joule-s2).
2. Vertical — alt: i16
A signed band index against the tileset's declared AltSchedule { base_m, width_m }. Band 0 is the datum surface; band n spans
[base_m + n·width_m, base_m + (n+1)·width_m). Negative bands are sub-surface
(bathymetry); positive bands carry atmosphere and orbit. A surface-only (2.5D)
tileset declares a single band of infinite width and uses only band 0. JSON has no
infinity, so that width's JSON form is null, which a reader MUST read back as
+∞; the canonical CBOR carries the float itself. A width that is NaN or −∞ has
no meaning and is refused.
3. Temporal — time: (start_tai_ms: i64, width_ms: u64)
A half-open [start, start+width) interval anchored to TAI. Bucket 0
(start == 0 && width == 0) is reserved for atemporal tiles — a coastline,
a border, bare terrain. Any other bucket is time-bound: a weather forecast hour,
a 28-day AIRAC cycle, an ADS-B snapshot. The temporal axis is first-class and
participates in the content id, so "this place on Tuesday 14:00Z" and "the same
place on Wednesday" are distinct, independently addressable, independently
signed tiles. This is what 3D Tiles lacks and what weather and flight navigation
require.
4. Detail — lod: u8
The within-tier detail level, independent of the S2 level (which is horizontal extent). A single splat tile at S2 level 20 MAY carry LODs 0..N of progressively denser Gaussians for streamed level-of-detail.
5. Canonicality
CellKey serializes through the family deterministic CBOR profile
(map_schema::canonical_cbor), so ContentId::of(&key) is a stable join key
across implementations. Conformance suite C1 pins the canonical CBOR and
content id of the cell-key vectors in ../conformance/v1/cell_key_vectors.json.