48225049f5
All checks were successful
no-vanity-metrics / Scan committed Markdown for vanity metrics (push) Successful in 4s
standards workspaces build + test / jouleclaw-rs (push) Successful in 1m49s
standards workspaces build + test / eoc-rs (push) Successful in 1m48s
standards workspaces build + test / aac-rs (push) Successful in 58s
standards workspaces build + test / arl-rs (push) Successful in 2m51s
standards workspaces build + test / jcp-rs (push) Successful in 1m21s
standards workspaces build + test / joule-code-rs (push) Successful in 42s
standards workspaces build + test / joulecontract-rs (push) Successful in 35s
standards workspaces build + test / proof-rs (push) Successful in 1m16s
standards workspaces build + test / map-rs (push) Successful in 31s
standards workspaces build + test / mesh-rs (push) Successful in 31s
standards workspaces build + test / sandbox-rs (push) Successful in 2m8s
standards workspaces build + test / openpay (push) Successful in 1m43s
standards workspaces build + test / joule-ui-rs (push) Successful in 4m32s
standards workspaces build + test / smart-byte-rs (push) Successful in 2m35s
standards workspaces build + test / jouledesk-rs (push) Successful in 3m32s
standards workspaces build + test / joulehook-rs (push) Successful in 3m24s
standards workspaces build + test / sense-rs (push) Successful in 3m15s
standards workspaces build + test / macOS energy backend (jcp-energy) (push) Successful in 2m42s
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]>
59 lines
2.7 KiB
Markdown
59 lines
2.7 KiB
Markdown
# Map sub-spec — The 4D cell key
|
|
|
|
Normative refinement of [SPEC §2](../SPEC.md). 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`](../conformance/v1/cell_key_vectors.json).
|