v0.5.3

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

Unreleased

0.5.3 - 2026-02-06

Changed

• Applied rustfmt to align formatting with CI expectations.
• Updated rkyv from 0.8.13 to 0.8.14
• Updated thiserror from 2.0.17 to 2.0.18
• Updated zerocopy from 0.8.33 to 0.8.34
• Updated getrandom from 0.3.4 to 0.4.0 (PR #82).
• Updated cudarc from 0.18.2 to 0.19.0 (PR #81).
• Updated glam from 0.30.10 to 0.31.0 (PR #80).
• Updated bytemuck from 1.24.0 to 1.25.0 (PR #79).
• Updated zerocopy from 0.8.34 to 0.8.37 (PR #79).
• Updated clap from 4.5.54 to 4.5.56 (PR #79).
• Updated bytes from 1.10.1 to 1.11.1 to address Dependabot alert #1 (PR #85).
• Updated quick-start docs to use the crate Result alias (PR #85).
• Updated robotics and autonomy docs for consistency (PR #85).
• Improved book quick-start onboarding with safer local test workflow guidance.
• Fixed Chapter 10 code-block fencing issues in the robotics/autonomy book chapter.
• Added book API contract generation and automated book-quality CI checks (fence parity, stale module-path scan, example reference validation).
• Reconciled key book sections with current crate API (quick start, robotics chapter GPU/temporal/compression/ROS2 snippets, troubleshooting/version notes).
• Fixed additional book markdown fence issues in Chapters 8, 13, and 15.
• Hardened container parsing/writing with frame count and frame-size limits to reduce malformed-input memory exhaustion risk.
• Made Layer<f64> aggregations NaN-safe by rejecting NaN inputs for numeric aggregation modes and using total ordering.
• Clarified AvoidBlockedCost behavior as hard-obstacle traversal (blocked cells are impassable).

0.5.2 - 2026-01-13

Changed

• Updated criterion from 0.7.0 to 0.8.1
• Updated bech32 from 0.11.0 to 0.11.1
• Updated zerocopy from 0.8.28 to 0.8.33
• Updated cudarc from 0.18.1 to 0.18.2
• Updated metal from 0.32.0 to 0.33.0
• Updated wgpu from 22.1.0 to 28.0.0
• Updated serde_json from 1.0.145 to 1.0.149
• Updated clap from 4.5.53 to 4.5.54
• Updated glam from 0.30.9 to 0.30.10
• Updated rkyv from 0.8.12 to 0.8.13
• Updated windows-sys from 0.59.0 to 0.60.2
• Updated Rust toolchain from 1.91.1 to 1.92.0
• Updated GitHub Actions actions/cache from v4 to v5

0.5.1 - 2025-12-05

Added

• ARM64 NEON intrinsics for Apple Silicon optimization
  • batch_manhattan_distance_neon(): SIMD-accelerated distance calculations
  • batch_bounding_box_query_neon(): SIMD-accelerated spatial queries
  • Auto-detection and dispatch on aarch64 targets
• AVX-512 support for Intel Xeon processors
  • batch_euclidean_distance_squared_avx512(): True 64-bit multiply via _mm512_mullox_epi64
  • 8-wide SIMD lanes (vs 4 with AVX2) for 2x throughput
  • Auto-detection via avx512f + avx512dq feature flags

Changed

• Updated zerocopy from 0.8.27 to 0.8.28
• Updated clap from 4.5.52 to 4.5.53
• Updated GitHub Actions actions/checkout from v5 to v6

Fixed

• Fixed version mismatch in src/lib.rs doc comment (v0.4.3 → v0.5.0)
• Removed unused COORD_BITS constant from Route64

Performance

• Added #[cold] and #[inline(never)] to error paths for better instruction cache utilization
  • Parity::invalid_parity_error() - cold path for parity validation
  • Route64::invalid_tier_error() - cold path for tier validation
  • Route64::coord_out_of_range_error() - cold path for range validation
• Added #[inline] hints to hot path functions (Parity::from_coords, Route64::new)

0.5.0 - 2025-11-19

Added

• Exploration Primitives for autonomous navigation
  • Frontier detection: clustering of unknown/free boundaries
  • Information gain calculation from viewpoints
  • Viewpoint candidate generation with ranking
  • Building blocks for Next-Best-View (NBV) planning
  • No prescribed policy - users control exploration strategy
• 3D Occupancy Framework with probabilistic sensor fusion
  • OccupancyLayer: Bayesian log-odds updates for probabilistic mapping
  • TemporalOccupancyLayer: Time-aware occupancy with decay for dynamic environments
  • CompressedOccupancyLayer: Block-based compression (10-100x) for large maps
  • GPU-accelerated ray casting (Metal for Apple Silicon, CUDA for NVIDIA)
  • ROS2 integration bridge with OccupancyGrid and PointCloud2 message types
• Layered 3D Mapping System
  • TSDFLayer: Truncated Signed Distance Fields for surface reconstruction
  • ESDFLayer: Euclidean Signed Distance Fields for path planning
  • MeshLayer: Surface extraction with marching tetrahedra
  • Unified measurement system for depth, TSDF, occupancy, and ESDF data
• Mesh Export Formats
  • PLY (Stanford Polygon File Format) - ASCII and binary
  • OBJ (Wavefront Object) - with normals
  • STL (Stereolithography) - ASCII and binary
• Advanced Occupancy Features
  • Temporal filtering with configurable decay rates
  • Multiple compression methods: None, LZ4, RLE, Octree
  • Multi-sensor fusion with noise tolerance
  • Ray integration for depth camera simulation
  • Frontier detection for autonomous exploration
• Examples
  • occupancy_fusion.rs: Bayesian fusion, multi-sensor integration
  • advanced_occupancy.rs: GPU, temporal filtering, compression, ROS2
  • tsdf_reconstruction.rs: Surface reconstruction from depth
  • mesh_reconstruction.rs: Mesh extraction and export
  • esdf_path_planning.rs: Distance field path planning

Performance

• GPU ray casting: 100-1000x speedup on large batches
• Compressed storage: 10-100x memory reduction for sparse maps
• Temporal pruning: Automatic cleanup of stale data
• Block-based compression: 8x8x8 voxel blocks for cache efficiency

Integration

• ROS2-compatible message types (nav_msgs, sensor_msgs)
• Serde serialization for JSON/CDR export
• BCC lattice integration with 14-neighbor connectivity

0.4.4 - 2025-11-18

Changed

• Updated Rust toolchain from 1.82.0 to 1.91.1
• Updated lz4_flex from 0.11.5 to 0.12.0
• Updated cudarc from 0.17.8 to 0.18.1
• Updated clap from 4.5.51 to 4.5.52
• Updated metal from 0.29.0 to 0.32.0
• Updated glam from 0.29.3 to 0.30.9
• Updated pollster from 0.3.0 to 0.4.0
• Updated crossterm from 0.28.1 to 0.29.0
• Updated zerocopy from 0.7.35 to 0.8.27

Fixed

• Fixed clippy lint issues for Rust 1.91.1 (removed invalid manual_is_multiple_of lint, added comparison_chain allows)
• Added advisory ignore for unmaintained paste crate (RUSTSEC-2024-0436) used by metal/wgpu dependencies
• Fixed CUDA backend for cudarc 0.17.7 API changes (CudaDevice → CudaContext)

0.4.3 - 2025-11-02

Added

• Interactive 3D Octahedral Maze Game CLI - Play mazes with difficulty levels (easy/medium/hard), compete against A* pathfinding, and track statistics
• BCC-14 Prim's Algorithm → A Demo* - Comprehensive example showing spanning tree generation on 549K BCC lattice nodes with pathfinding
• GitHub Community Standards - CONTRIBUTING.md, issue templates, PR template, and community guidelines
• Security Enhancements - CodeQL security analysis workflow with automatic scanning
• CLI utility functions: encode/decode coordinates, calculate distances, get BCC neighbors

Changed

• Updated ordered-float from 4.6.0 to 5.1.0 (major version)
• Updated rand from 0.8.5 to 0.9.2 (major version)
• Updated criterion (dev) from 0.5.1 to 0.7.0
• Updated proptest (dev) from 1.8.0 to 1.9.0
• Updated github/codeql-action workflow from v3 to v4
• Simplified CI/CD pipeline for better reliability
• Updated GitHub Actions MSRV check to Rust 1.77
• Revised Code of Conduct for improved clarity

Fixed

• Downgraded half dependency to v2.4.1 to avoid yanked version
• Fixed all remaining clippy errors and warnings
• Fixed cargo-deny configuration for better compatibility
• Fixed CUDA test failures with proper panic handling
• Fixed AVX-512 type errors in SIMD batch operations
• Fixed platform-specific GPU module guards

Notes

• All dependency updates maintain compatibility with existing code
• Test suite passes with 100/100 tests
• No breaking API changes in public interface
• Maze game accessible via cargo run --release --features cli -- play
• BCC-14 demo runs in 131ms for tree generation, 1ms for pathfinding

0.4.2 - 2025-10-16

Added

• First crates.io release
• Perfect code quality (zero compiler warnings)
• Comprehensive documentation

Changed

• Package optimized to 91 KB compressed size
• All tests passing (101/101)

Fixed

• Fixed all clippy warnings
• Applied rustfmt to entire codebase

0.4.0 - 2025-10-15

Added

• Major performance optimizations
• SIMD batch operations
• Parallel processing improvements

Changed

• Morton decode optimization (37% speedup)
• Parallel overhead fix (86% speedup for 10K batches)

v0.5.2

Changed

• Updated criterion from 0.7.0 to 0.8.1
• Updated bech32 from 0.11.0 to 0.11.1
• Updated zerocopy from 0.8.28 to 0.8.33
• Updated cudarc from 0.18.1 to 0.18.2
• Updated metal from 0.32.0 to 0.33.0
• Updated wgpu from 22.1.0 to 28.0.0
• Updated serde_json from 1.0.145 to 1.0.149
• Updated clap from 4.5.53 to 4.5.54
• Updated glam from 0.30.9 to 0.30.10
• Updated rkyv from 0.8.12 to 0.8.13
• Updated windows-sys from 0.59.0 to 0.60.2
• Updated Rust toolchain from 1.91.1 to 1.92.0
• Updated GitHub Actions actions/cache from v4 to v5

Release v0.5.1

What's Changed

• deps(deps): bump the rust-dependencies group with 2 updates by @dependabot[bot] in #67
• ci(deps): bump actions/checkout from 5 to 6 by @dependabot[bot] in #66

Full Changelog: v0.5.0...v0.5.1

Release v0.5.0

What's Changed

• Update README and book with autonomous mapping stack features by @FunKite in #53
• Claude/update readme and book 01 mgv1td w5c hv upa ek4 rbazt by @FunKite in #54
• Claude/update readme and book 01 mgv1td w5c hv upa ek4 rbazt by @FunKite in #55
• Improve feature table presentation: remove negative X marks by @FunKite in #56
• Update README to reference book instead of whitepaper by @FunKite in #58
• Update test framework and automated checks for release 0.5.0 by @FunKite in #57
• Fix CI failures: address clippy warnings and doctest error by @FunKite in #60
• Add comprehensive benchmark suite for v0.5.0 autonomous mapping features by @FunKite in #59
• Add comprehensive benchmark summary table for v0.5.0 by @FunKite in #61
• Claude/benchmark summary table 01 gj sg e864 x qr gus49 qwa ed n by @FunKite in #62
• Claude/benchmark summary table 01 gj sg e864 x qr gus49 qwa ed n by @FunKite in #63
• Fix incorrect academic references in resources.md by @FunKite in #64
• Fix benchmark code quality issues from code review by @FunKite in #65

Full Changelog: v0.4.4...v0.5.0

Release v0.4.4

What's Changed

• deps(deps): bump metal from 0.29.0 to 0.32.0 by @dependabot[bot] in #23
• deps(deps): bump pollster from 0.3.0 to 0.4.0 by @dependabot[bot] in #25
• deps(deps): bump clap from 4.5.50 to 4.5.51 in the rust-dependencies group by @dependabot[bot] in #22
• deps(deps): bump crossterm from 0.28.1 to 0.29.0 by @dependabot[bot] in #24
• deps(deps): bump glam from 0.29.3 to 0.30.9 by @dependabot[bot] in #26
• Add comprehensive code review report by @FunKite in #27
• Claude/code review 011 c uw zy2c c3 fkd5i q5dkqwf by @FunKite in #28
• Apply Code Review Improvements by @FunKite in #29
• deps(deps): bump zerocopy from 0.7.35 to 0.8.27 by @dependabot[bot] in #30
• deps(deps): bump cudarc from 0.12.1 to 0.17.7 by @dependabot[bot] in #31
• Improve README with enhanced structure and comprehensive documentation by @FunKite in #32
• Claude/book part 1 foundations 015 jjv ph5 q hb ffh mfry2 q1 gf by @FunKite in #33
• Claude/book part 1 foundations 015 jjv ph5 q hb ffh mfry2 q1 gf by @FunKite in #34
• Add comprehensive book enhancement suggestions by @FunKite in #36
• Exclude book directory from crates.io publication by @FunKite in #35
• Expand Part III chapters with comprehensive technical content by @FunKite in #37
• Expand Part III chapters with comprehensive technical content by @FunKite in #38
• Claude/book enhancements continued 01 d48okmw x99 uk2 vvi5 q nh ud by @FunKite in #39
• Claude/book enhancements continued 01 d48okmw x99 uk2 vvi5 q nh ud by @FunKite in #40
• Update BOOK_ENHANCEMENT_SUGGESTIONS.md with completed Chapters 5-9 by @FunKite in #41
• Complete Part IV and Part V chapters and critical appendices by @FunKite in #42
• Claude/address identified issues 01 bx2qir5 um25g krv eb up y8e by @FunKite in #43
• Complete Appendices D-E and add rust-toolchain.toml by @FunKite in #44
• Complete Appendices F-H with comprehensive technical content by @FunKite in #45
• Claude/book enhancement suggestions 01 n73 anvoo s wb7 s du ab pdny e by @FunKite in #46
• Create practical resources guide and update enhancement tracking by @FunKite in #47
• Enhance book documentation: expand glossary and update progress tracking by @FunKite in #48
• Complete code quality enhancements: add language specifiers to all co… by @FunKite in #49
• deps(deps): bump lz4_flex from 0.11.5 to 0.12.0 by @dependabot[bot] in #52
• deps(deps): bump cudarc from 0.17.8 to 0.18.1 by @dependabot[bot] in #51
• deps(deps): bump clap from 4.5.51 to 4.5.52 in the rust-dependencies group by @dependabot[bot] in #50

Full Changelog: v0.4.3...v0.4.4

Release v0.4.3

Release Notes: OctaIndex3D v0.4.3

Release Date: 2025-11-02
Version: 0.4.3
Repository: https://github.com/FunKite/OctaIndex3D
Crates.io: https://crates.io/crates/octaindex3d

---

🎮 Interactive 3D Maze Game & Advanced Demos

This release introduces an interactive CLI maze game built on the BCC lattice, along with comprehensive demos showcasing the power of BCC-14 connectivity for pathfinding algorithms.

---

🆕 What's New in v0.4.3

Interactive 3D Octahedral Maze Game CLI

• Play mazes with difficulty levels: Easy, Medium, and Hard
• Compete against A pathfinding:* See how your solution compares to optimal paths
• Track statistics: View your solve times, path lengths, and efficiency
• Full CLI integration: Run with cargo run --release --features cli -- play

BCC-14 Prim's Algorithm → A* Demo

• Comprehensive showcase of spanning tree generation on 549K BCC lattice nodes
• Prim's randomized algorithm: Builds maze structure using all 14 BCC neighbors
• A pathfinding:* Finds shortest paths through carved tree structure
• Performance metrics:
  • Build time: 131 ms (8x under 1.0s target)
  • Solve time: 1 ms (200x under 200ms target)
  • Memory: 11 MB (32x under 350MB target)
• Dynamic seeding: Reproducible runs with --seed=<u64> argument
• 5/5 validation checks: Spanning tree property, full coverage, frontier deduplication, path verification, BFS cross-check

GitHub Community Standards

• CONTRIBUTING.md - Contribution guidelines
• Issue templates - Bug reports and feature requests
• PR template - Pull request guidelines
• Community guidelines - Code of conduct improvements

Security Enhancements

• CodeQL security analysis - Automatic scanning workflow
• Dependency auditing - Enhanced security monitoring

CLI Utility Functions

• Encode/decode coordinates - Convert between coordinate systems
• Calculate distances - BCC lattice distance calculations
• Get BCC neighbors - Query all 14 neighbors for any point

---

🔄 Dependency Updates

Major Version Updates

• ordered-float 4.6.0 → 5.1.0 (breaking change)
• rand 0.8.5 → 0.9.2 (breaking change)
• criterion (dev) 0.5.1 → 0.7.0

Minor Updates

• proptest (dev) 1.8.0 → 1.9.0
• github/codeql-action v3 → v4

Other Changes

• Simplified CI/CD pipeline for better reliability
• Updated GitHub Actions MSRV check to Rust 1.77
• Revised Code of Conduct for improved clarity

---

🐛 Bug Fixes

1. Half Dependency Fix

   • Downgraded half to v2.4.1 to avoid yanked version
   • Resolved transitive dependency conflict via Criterion → CBOR stack

2. Code Quality Improvements

   • Fixed all remaining clippy errors and warnings
   • Fixed cargo-deny configuration for better compatibility

3. Platform-Specific Fixes

   • Fixed CUDA test failures with proper panic handling
   • Fixed AVX-512 type errors in SIMD batch operations
   • Fixed platform-specific GPU module guards

---

📦 Installation

From Crates.io

[dependencies]
octaindex3d = "0.4.3"

# With CLI features for the maze game
octaindex3d = { version = "0.4.3", features = ["cli"] }

# With recommended features (default includes parallel + simd)
octaindex3d = { version = "0.4.3", default-features = true }

# With all optional features
octaindex3d = { version = "0.4.3", features = ["hilbert", "container_v2", "gis_geojson", "cli"] }

Play the Maze Game

# Install from crates.io
cargo install octaindex3d --features cli

# Or run from source
git clone https://github.com/FunKite/OctaIndex3D
cd octaindex3d
cargo run --release --features cli -- play --difficulty easy

Run the BCC-14 Demo

# From source
cargo run --release --example bcc14_prim_astar_demo

# With custom seed for reproducibility
cargo run --release --example bcc14_prim_astar_demo -- --seed=42

---

✨ Key Features

• Three ID Types: Galactic128 (global), Index64 (Morton), Route64 (local routing)
• High Performance: Cross-platform optimizations (Apple Silicon, AMD, Intel)
• 14-Neighbor Connectivity: More isotropic than cubic grids (6 neighbors)
• Space-Filling Curves: Morton and Hilbert encoding for spatial locality
• Hierarchical Refinement: 8:1 parent-child relationships across resolutions
• Bech32m Encoding: Human-readable IDs with checksums
• Compression: LZ4 (default) and optional Zstd support
• Streaming Container Format: Append-friendly compressed spatial data storage
• GeoJSON Export: WGS84 coordinate export for GIS integration
• Interactive CLI: 3D maze game with pathfinding demonstrations

---

🔧 Feature Flags

Performance Features (Enabled by Default)

• parallel - Multi-threaded batch operations with Rayon
• simd - SIMD-accelerated operations (BMI2, AVX2, NEON)
• serde - Serialization support
• lz4 - LZ4 compression

Optional Features

• cli - Interactive CLI maze game and utilities
• hilbert - Hilbert64 space-filling curve (better locality than Morton)
• container_v2 - Streaming container format with checkpoints
• gis_geojson - GeoJSON export with WGS84 coordinates
• zstd - Zstd compression (in addition to LZ4)
• pathfinding - Advanced pathfinding with petgraph

GPU Features (Not Recommended)

• gpu-metal, gpu-vulkan, gpu-cuda - CPU is 10x faster

---

🎯 BCC-14 Connectivity Advantages

The BCC (Body-Centered Cubic) lattice with 14-neighbor connectivity offers significant advantages over traditional cubic grids:

• More isotropic: Equal distance to all 14 neighbors
• Better pathfinding: Diagonal moves integrated into lattice structure
• Optimal packing: Truncated octahedral cells tile 3D space perfectly
• Efficient mazes: Prim's algorithm preserves optimal connectivity
• Theoretical optimality: Many paths at or near theoretical minimum length

---

📊 Cross-Platform Performance

Apple Silicon (M1 Max)

• Morton Decode: 157M ops/sec
• Batch Neighbors: 50M routes/sec (10K batch)
• Index64 Encode: 467M elem/sec
• Maze Generation: 131 ms (549K nodes)
• A Pathfinding:* 1 ms (tree-constrained)

AMD EPYC 7R13 (Zen 3)

• Morton Decode: 505M ops/sec (BMI2 hardware)
• Batch Neighbors (small): 32.1M routes/sec

Intel Xeon 8488C (Sapphire Rapids)

• Morton Decode: 424M ops/sec
• Batch Neighbors (large): 37.8M routes/sec

---

📚 Documentation

Included in Crate:

• README.md - Quick start and examples
• LICENSE - MIT License

Available on GitHub:

• WHITEPAPER.md - Comprehensive technical analysis
• PERFORMANCE.md - Performance guide and benchmarks
• CPU_COMPARISON.md - Cross-platform performance analysis
• GPU_ACCELERATION.md - Why CPU is faster than GPU
• OPTIMIZATION_GUIDE.md - Tier-1 CPU/GPU optimization guide
• CONTRIBUTING.md - How to contribute to the project

---

🔄 Migration from v0.4.2

v0.4.3 maintains API compatibility with v0.4.2. Update your Cargo.toml:

[dependencies]
octaindex3d = "0.4.3"

Breaking Changes in Dependencies

Note that ordered-float and rand have been updated to new major versions. If you use these dependencies directly, you may need to update:

• ordered-float 4.x → 5.x
• rand 0.8.x → 0.9.x

---

🎯 Performance Tips

Compiler Flags (Recommended)

RUSTFLAGS="-C target-cpu=native" cargo build --release

Enables:

• Apple Silicon: NEON instructions, Firestorm/Icestorm optimizations
• AMD: BMI2, AVX2, Zen 3+ tuning
• Intel: BMI2, AVX2, architecture-specific tuning

Batch Size Recommendations

• Small (<100): Default API, optimized for prefetching
• Medium (100-50K): Batch operations, cache-blocked processing
• Large (>50K): Parallel processing automatically engaged

---

✅ Quality Metrics

✓ Compiler warnings: 0
✓ Test pass rate: 100% (110/110)
✓ Clippy warnings: 0
✓ Build time: ~5.5s
✓ Documentation: Complete

---

🙏 Acknowledgments

This release was developed with extensive AI assistance:

• Interactive maze game implementation by Claude (Anthropic)
• BCC-14 algorithm demos and validation
• Community standards and security enhancements
• Dependency management and testing infrastructure

---

📝 License

Licensed under the MIT License.

Copyright (c) 2025 Michael A. McLarney

---

🔗 Links

• Repository: https://github.com/FunKite/OctaIndex3D
• Documentation: https://docs.rs/octaindex3d
• Crates.io: https://crates.io/crates/octaindex3d
• Issues: https://github.com/FunKite/OctaIndex3D/issues

---

🔮 Future Improvements

1. Monitor Half Dependency - Watch for future half releases (currently pinned to v2.4.1)
2. AVX-512 Implementation - Potential 2x speedup for Intel Xeon
3. Improved AMD Large Batch Performance - Target 40M routes/sec
4. Advanced NEON Optimizations - Further Apple Silicon improvements

---

Thank you for using OctaIndex3D!

For detailed technical information, visit the GitHub repository.