| Crates.io | lnmp-spatial |
| lib.rs | lnmp-spatial |
| version | 0.5.16 |
| created_at | 2025-11-21 20:22:17.716198+00 |
| updated_at | 2025-12-19 10:14:09.569564+00 |
| description | Spatial awareness types and logic for LNMP protocol |
| homepage | https://lnmp.io |
| repository | https://github.com/lnmplang/lnmp-protocol |
| max_upload_size | |
| id | 1944203 |
| size | 120,745 |
Spatial awareness types and hybrid protocol for the LNMP ecosystem, enabling deterministic physical-world interaction in LLM → Machine → Robot → Simulation chains.
FID Registry: Spatial FIDs are defined in the Standard range (256-511) in
registry/fids.yaml.
Add to your Cargo.toml:
[dependencies]
lnmp-spatial = { path = "../lnmp-protocol/crates/lnmp-spatial" }
use lnmp_spatial::*;
// Create a position
let pos = Position3D { x: 10.0, y: 20.0, z: 30.0 };
// Encode to binary
let mut buffer = Vec::new();
encode_spatial(&SpatialValue::S2(pos), &mut buffer)?;
// Decode from binary
let decoded = decode_spatial(&mut buffer.as_slice())?;
use lnmp_spatial::delta::Delta;
let start = Position3D { x: 10.0, y: 20.0, z: 30.0 };
let end = Position3D { x: 11.0, y: 19.0, z: 32.0 };
// Compute delta (only differences)
let delta = Position3D::compute_delta(&start, &end);
// delta = { dx: 1.0, dy: -1.0, dz: 2.0 }
// Apply delta
let reconstructed = Position3D::apply_delta(&start, &delta);
assert_eq!(reconstructed, end);
use lnmp_spatial::protocol::{SpatialStreamer, SpatialStreamerConfig};
let config = SpatialStreamerConfig {
abs_interval: 100, // ABS frame every 100 frames
enable_prediction: true, // Enable predictive delta
max_prediction_frames: 3, // Max 3 predicted frames
};
let mut streamer = SpatialStreamer::with_config(config);
// Sender
let frame = streamer.next_frame(&robot_state, timestamp_ns)?;
// Receiver
let state = streamer.process_frame(&frame)?;
┌─────────────────────────────────────┐
│ Application (Robot Control) │
├─────────────────────────────────────┤
│ Hybrid Protocol (SpatialStreamer) │ ← Phase 3
│ - ABS/DELTA mixing │
│ - Sequence tracking │
│ - Predictive fallback │ ← Phase 5
├─────────────────────────────────────┤
│ Frame Layer │ ← Phase 4
│ - CRC32 checksum │
│ - Nanosecond timestamp │
├─────────────────────────────────────┤
│ Delta Layer │ ← Phase 2
│ - Compute delta │
│ - Apply delta │
├─────────────────────────────────────┤
│ Binary Codec │ ← Phase 1
│ - Encode/Decode │
│ - Type system │
└─────────────────────────────────────┘
Normal Operation (No Packet Loss):
Sender Receiver
│ │
├─[Frame 0: ABS]────────>│ ✓ Reset state
├─[Frame 1: DELTA]──────>│ ✓ Apply delta
├─[Frame 2: DELTA]──────>│ ✓ Apply delta
├─[Frame 3: DELTA]──────>│ ✓ Apply delta
...
├─[Frame 100: ABS]──────>│ ✓ Drift correction
Packet Loss (Predictive Mode):
Sender Receiver
│ │
├─[Frame 97: DELTA]─────>│ ✓ Apply delta
├─[Frame 98: DELTA]─────>│ ✓ Apply delta, Predict: 99
├─[Frame 99: DELTA]─X │ ❌ LOST → 🔮 Use prediction
├─[Frame 100: ABS]──────>│ ✓ Confirm/correct
Benchmarks on Apple Silicon M-series:
| Operation | Latency | Throughput |
|---|---|---|
| Encode Position3D | ~2.8 ns | ~357 M/s |
| Decode Position3D | ~2.2 ns | ~454 M/s |
| Compute Delta | ~5 ns | ~200 M/s |
| Spatial Transform | ~7.5 ns | ~133 M/s |
| Full Frame (Hybrid) | ~50 ns | ~20 M/s |
Bandwidth Savings:
cargo run --example robot
cargo run --example stream
cargo run --example jitter_sim
cargo run --example reflex_sim
"Robot arm moves with small delta steps, but resets with absolute position every breath."
For applications where prediction is unsafe (e.g., surgery robots):
let config = SpatialStreamerConfig {
abs_interval: 10, // More frequent resets
enable_prediction: false, // Disable prediction
max_prediction_frames: 0,
};
See docs.rs or run:
cargo doc --open
MIT OR Apache-2.0