spatial_codecs 0.2.4

High-throughput, format-agnostic encoding/decoding for spatial data (point clouds, Gaussian splats, …)
Documentation

spatial_codecs

High-throughput, format-agnostic encoding/decoding for spatial data (point clouds, Gaussian splats, …), built around a simple idea:

Every encoded payload starts with a 3-byte magic tag. The decoder reads those first bytes and automatically selects the right codec.

This makes the pipeline much easier to evolve: producers can switch codecs without forcing all consumers to be reconfigured.

spatial_codecs is designed for throughput:

  • encoding/decoding APIs that write into caller-provided buffers
  • minimal allocations and copy-avoidance where possible
  • an FFI layer that favors flat arrays for interop and speed

What data types does it support?

We support spatial primitives from the spatial_utils crate (e.g. points and splats). Not all codecs support all spatial types.

When a direct path is missing, the library will:

  1. perform a fast conversion when possible, or
  2. return a clear, typed error when it cannot.

Adding the missing case is intentionally straightforward—see docs/design.md.

Crate structure

  • src/decoder.rs - format-agnostic decoding (dispatch by 3-byte magic)
  • src/encoder.rs - format-agnostic encoding (explicit EncodingParams)
  • src/codecs/* - per-codec adapters
  • src/ffi.rs - C ABI (and binding generation support)

More details:

  • docs/design.md - architecture, dispatch, conversions, performance notes
  • docs/ffi.md - how to build and use the C / C# bindings

Getting started (Rust)

Add the crate:

[dependencies]
spatial_codecs = "0.1.0"
spatial_utils = "0.1.0"

Tip: check crate versions on crates.io/crates/spatial_codecs and crates.io/crates/spatial_utils for the latest release.

Encode into a reusable Vec<u8>:

use spatial_codecs::encoder::{encode_into_generic, EncodingParams};
use spatial_utils::point::Point3RgbF32;

let points: Vec<Point3RgbF32> = vec![
    Point3RgbF32::new(0.0, 0.0, 0.0, 255, 0, 0),
    Point3RgbF32::new(1.0, 2.0, 3.0, 0, 255, 0),
];

let params = EncodingParams::default();
let mut out = Vec::with_capacity(1024);

encode_into_generic::<Point3RgbF32, f32>(&points, &params, &mut out)?;

Decode without knowing the codec up front:

use spatial_codecs::decoder::decode_into;
use spatial_utils::point::Point3RgbF32;

let mut decoded: Vec<Point3RgbF32> = Vec::new();
decode_into(&out, &mut decoded)?;

Optional codecs

Some codecs are behind Cargo features to keep the default build lean.

Example: enable the Draco bridge via:

spatial_codecs = { version = "0.1.0", default-features = false, features = ["draco"] }

Building for FFI

Build optimized artifacts:

cargo build --release

You’ll typically load the shared library from C# (P/Invoke) or from C/C++:

  • Linux: libspatial_codecs.so
  • macOS: libspatial_codecs.dylib
  • Windows: spatial_codecs.dll

Static libraries may also be produced (.a / .lib) depending on your toolchain.

Generate C/C++ and C# bindings:

cargo run --release --bin pc_generate_bindings

This writes the generated bindings under bindings/.

Examples

See the examples/ directory for end-to-end samples. They are intentionally written to be allocation-light and suitable for high-throughput pipelines.

If you’re extending codec/type coverage, start with docs/design.md.