88 lines
4.2 KiB
Markdown
88 lines
4.2 KiB
Markdown
# Local voxel contract v1 (M5.1)
|
|
|
|
This is the scoped experiment in [ADR-0042](../adr/0042-local-voxel-contract.md).
|
|
Public API: `include/evo/world/coordinates.hpp`. It implements pure address mapping
|
|
and logical cell validation, not a world container or a persistent file format.
|
|
|
|
## Frames and units
|
|
|
|
Right-handed Cartesian frame, +Z up, X cross Y = Z. `VoxelAddress` contains signed
|
|
cell indices, not metres. `ChunkAddress` contains signed chunk indices.
|
|
`LocalCell` contains unsigned cell offsets within a chunk. `MetricCorner` contains
|
|
named signed millimetres. No implicit conversion to the old periodic 2D particle
|
|
coordinates exists. The 2D habitat/effective-depth mapping waits for M6.1.
|
|
|
|
Per-axis voxel range is [-1,048,576, 1,048,576). Cell v owns the metric interval
|
|
[v*1000, (v+1)*1000) mm. The positive outer face exists geometrically but is not
|
|
another addressable cell. There is no wraparound or clamping. Negative Z is ordinary
|
|
volume, so the contract is not a surface heightfield. No origin shift is implicit.
|
|
|
|
## Mapping and failure contract
|
|
|
|
Callers explicitly pass edge N in {8,16,32,64}. M5.2 will compare those candidates;
|
|
there is no default chunk size. Valid chunk axes are [-1,048,576/N, 1,048,576/N).
|
|
Offsets satisfy 0 <= local < N. Each chunk covers exactly N cubed disjoint cells.
|
|
|
|
```
|
|
voxel --split(edge)--> {chunk, local} --join(edge)--> same voxel
|
|
local --ordinal(edge)--> x + N*(y + N*z) --local_from_ordinal(edge)--> same local
|
|
voxel --lower_corner_mm()--> signed metric corner
|
|
```
|
|
|
|
For edge 16, on any axis:
|
|
|
|
| Voxel | Chunk | Local |
|
|
|---:|---:|---:|
|
|
| -17 | -2 | 15 |
|
|
| -16 | -1 | 0 |
|
|
| -1 | -1 | 15 |
|
|
| 0 | 0 | 0 |
|
|
| 15 | 0 | 15 |
|
|
| 16 | 1 | 0 |
|
|
|
|
All functions return `std::expected` and leave arguments unchanged. Invalid edge
|
|
is reported before address validation; join checks chunk before local coordinates.
|
|
Metric conversion validates voxel bounds before multiplying. Accepted ordinal range
|
|
is [0,N cubed). Max N cubed is 262,144; all intermediate arithmetic is bounded.
|
|
Inputs at INT64_MIN/MAX and UINT32_MAX must fail safely, not overflow.
|
|
|
|
| Error | Meaning |
|
|
|---|---|
|
|
| invalid_edge | Candidate edge not supported |
|
|
| voxel_out_of_range | Any signed voxel axis outside the local envelope |
|
|
| chunk_out_of_range | Any signed chunk axis outside the edge-specific envelope |
|
|
| local_out_of_range | Any local offset >= edge |
|
|
| ordinal_out_of_range | Ordinal >= edge cubed |
|
|
| invalid_cell | Fill >65,535 or void/material-fill mismatch |
|
|
|
|
## Logical cell and identity boundaries
|
|
|
|
`CellSample::create(MaterialId, fill)` produces a validated value. Material zero
|
|
and fill zero denote void. Nonzero material requires positive fill. Fill/65,535 is
|
|
an exact rational fraction of the 1m-cubed cell; integer volume/mass conversion must
|
|
carry remainders under a later accounting contract. No geometry shape, material
|
|
density, light, moisture, nutrients or energy are inferred from this value.
|
|
|
|
An unknown nonzero material key is structurally valid here; M5.3's versioned table
|
|
must resolve it or reject it. Native sizeof/alignment is not an encoded layout.
|
|
Palette compression, uniform storage and varying pages belong to M5.2. Smooth
|
|
meshing needs additional geometry information and a separate comparison/ADR.
|
|
|
|
A chunk is storage addressing, a region is simulation authority, and an ecological
|
|
cell is a resource/model domain. They are not interchangeable IDs. M5.1 functions
|
|
operate in one caller-selected frame; no function compares coordinates from different
|
|
worlds or frames. Persisting/exchanging keys requires those identities and versions
|
|
in the enclosing schema. No coordinate or material key allocates resident data.
|
|
|
|
## Acceptance and next step
|
|
|
|
Tests must prove floor mapping against an independently constructed interval oracle,
|
|
not merely split(join(x)); exhaust every ordinal for every candidate edge; test all
|
|
axes, seams, envelope corners and invalid extremes. M5.1 is complete when those
|
|
contracts build and pass. M5.2 next compares compact chunk layouts and sizes; it must
|
|
not infer a preferred storage representation from these C++ value types.
|
|
|
|
M5.2 follow-up: [ADR-0043](../adr/0043-chunk-layout.md) now selects edge 16 and
|
|
uniform/palette/dense geometry for the bounded M5 world. This does not remove the
|
|
explicit candidate edges from the coordinate API or define a wire format.
|