Elixir facade over the spatial Rust NIFs (EXCP, GSPL, binary PLY).

Callers fall back to pure Elixir when available?/0 is false or a call returns :nif_not_loaded. This module defines the cross-language ABI: row tuple shapes must match native/ex_codecs_native/src/spatial.rs.

Chunk semantics

Unpack NIFs return {:ok, {rows, next_offset}}. Pass at most chunk_size/0 (4096) rows per call and advance offset from next_offset. Whole-payload decode paths loop the same way. A partial final record is silently skipped (the unpack breaks); callers can detect truncation by comparing next_offset to the expected body size.

Data coercion

Out-of-range color bytes are clamped to [0, 255] (not wrapped). Missing SH coefficients are zero-filled to the declared sh_rest length. Both coercions are lossy: a round-trip through encode may not reproduce the original if the input contained out-of-range values.

Row formats

• EXCP point row: {x, y, z, color, normal} where color / normal are nil or tuples matching header flags
• GSPL gaussian row: {{x, y, z}, {r, g, b}, opacity, {sx, sy, sz}, {rw, rx, ry, rz}, sh_list}
• PLY binary: flat numeric lists per vertex, typed by ply_type_tag/1

mmap

Do not truncate or replace a file while an mmap resource from mmap_open/1 is live — concurrent truncation can SIGBUS and kill the BEAM. Prefer accel: false / plain IO for untrusted paths.

This module is intentional infrastructure; HexDocs may still group it under internals depending on ExDoc filters.