plozone 0.1.2

3D spatial zone engine: geofencing, octree hole-scanning, realtime sync (WebSocket + QUIC + io_uring), voxel pathfinding, and AV sensor fusion.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

# plozone

**3D spatial zone engine — geofencing, octree hole-scanning, realtime sync,
voxel pathfinding, and AV sensor fusion. One crate, every domain.**

[![crates.io](https://img.shields.io/crates/v/plozone)](https://crates.io/crates/plozone)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![tests](https://img.shields.io/badge/tests-105%20passing-brightgreen)](#building-and-testing)

---

## Install

```toml
[dependencies]
plozone = { version = "0.1", features = ["full"] }
```

## Quick start

```rust
use plozone::{
    coord::EnuConverter, octree::OctreeNode,
    store::ZoneStore, zone::{Zone, ZoneEntry},
    scan::{run_scan, ScanMode},
};

// WGS84 origin in Ho Chi Minh City
let conv = EnuConverter::new(10.7626, 106.6601, 0.0);

let store = ZoneStore::from_entries(&[
    ZoneEntry::new(1, Zone::Cylinder {
        center: [10.7626, 106.6601], radius_m: 50.0,
        z_min: 0.0, z_max: 20.0,
    }),
], &conv);

// Is this point inside the zone?
let hits = store.query_geodetic(10.7626, 106.6601, 5.0, &conv);
assert_eq!(hits.as_slice(), &[1]);

// Scan for unsampled regions in the octree
let octree = OctreeNode::new([0.0; 3], 64.0);
let result = run_scan(&octree, &store, 1, &ScanMode::Coarse { depth: 4 });
println!("coverage: {:.1}%", result.coverage_pct);
```

## Why Plozone?

Every spatial project reinvents the same primitives. Plozone answers *is this
point inside a zone?*, *did the entity enter or leave?*, and *is this region
fully scanned?* across real-world geospatial, game maps, robotics, autonomous
vehicles, and IoT — with one consistent API.

## Architecture

```
User Input (WGS84 / game / sensor)    ──►  CoordSystem
                                              │
ZoneStore ◄── R-tree indexed ── Box<dyn ZoneShape>
    │                    │
    ├── query_enu       < 1 µs point-in-zone
    ├── query_geodetic   any lat/lon/alt
    ├── layer queries    filtered by priority
    └── top_priority     tie-breaks on id

OctreeNode ── adaptive subdivision (max depth 17, ~4mm voxels)
    │
    ├── run_scan         single/multiscale hole detection
    ├── range_query      points in bounding box
    └── depth_for_accuracy

ZoneServer ── WebSocket + QUIC + io_uring ── sharded to 300k entities
```

**Two-layer zone model:** `enum Zone` (wire-safe, 6+ built-in shapes, serde) +
`trait ZoneShape` (custom dynamic shapes). Mix both in the same store.

## Features

| Feature       | Provides |
|---------------|----------|
| *(default)*   | `coord`, `zone`, `octree`, `store`, `scan` — zero deps |
| `net`         | Postcard wire codec, LZ4/ZSTD, dead-reckoning |
| `server`      | WebSocket server + client, sharding, hysteresis debounce |
| `quic`        | QUIC transport (quinn + rustls, datagrams) |
| `io_uring`    | Linux io_uring transport (tokio-uring) |
| `pathfinding` | 3D voxel A\* over octree |
| `game`        | GameWorld, LayeredMap, ChunkedGameWorld, PortalSystem |
| `terrain`     | Marching cubes, OBJ/PLY export |
| `av`          | EKF fusion, sensor FOV, safety envelope, HD map, V2X |
| `bevy`        | Bevy ECS plugin (Spatial3dPlugin, ZoneTracker) |
| `embedded`    | no_std linear-scan store |
| `lidar`       | Pose/quaternion math, scan ingestion |
| `parallel`    | Rayon-accelerated scanning |
| `geo`         | geo-types interop |
| `prometheus`  | Metrics exporter |
| `mimalloc`    | MiMalloc global allocator |

```toml
plozone = { version = "0.1", features = ["server", "quic"] }
```

## Transports

| Transport | Feature | Latency p99 | Use case |
|---|---|---|---|
| WebSocket | `server` | ~5 ms | Browser clients |
| QUIC | `quic` | ~2 ms | Mobile, 0-RTT reconnect |
| io_uring | `io_uring` | < 1 ms | Linux, max throughput |

All share the same postcard wire format and `ZoneServer` core.

## Scale

| Tier | Entities | Latency p99 |
|---|---|---|
| Single process | ~5k | < 5 ms |
| Sharded ×16 | ~80k | < 2 ms |
| Sharded ×64 + io_uring | ~300k | < 1 ms |
| Multi-process | 5M+ | < 5 ms |

## Performance

| Operation | Time |
|---|---|
| 1k zone point query | ~730 ns |
| 1k octree insert | ~435 µs |
| Hole scan depth 4 | ~12 µs |
| WGS84 → ENU | ~128 ns |
| ENU → WGS84 | ~655 ns |

## Build & test

```sh
cargo build                              # core (zero deps)
cargo test --features full               # 105 tests
cargo bench --features full              # criterion
cargo clippy --features full -- -D warnings
```

## License

MIT. See [LICENSE](LICENSE).

## Links

- [API docs](https://docs.rs/plozone) · [GitHub](https://github.com/fentz26/plozone) · [crates.io](https://crates.io/crates/plozone)
- [Design document](PLOZONE.md) · [Contributing](CONTRIBUTING.md)