Sonar 3D Reconstruction
Getting Started
Sonar 3D Reconstruction
Features
Quick Start
Launch Arguments
Configuration
Config Files
Key Parameters (common.yaml)
Topics
Subscribe
Publish
Nodes
Build
Dependencies
Runtime Dependencies
File Structure
Coordinate System
Design Documents
Intensity-Weighted Log-Odds (IWLO) Probability Update
Overview
1. Background
Limitations of Existing Methods
IWLO Design Goals
2. Mathematical Formulation
2.1 Probability-Log-Odds Transformation
2.2 Intensity-to-Weight Transformation
2.3 Learning Rate Decay
2.4 Adaptive Scaling (Bidirectional Protection)
2.5 Update Formula
3. Algorithm Pseudocode
4. Parameter Tuning Guide
4.1 Sharpness (
\(\gamma\)
)
4.2 Decay Rate (
\(\lambda\)
)
4.3 Minimum Alpha (
\(\alpha_{min}\)
)
5. Related Documents
API Reference
Design Documents
6. References
Changelog
Octree Mapping Design
Overview
1. Data Structure
1.1 Octree Structure
1.2 Voxel Key
1.3 Dual Storage Strategy
2. Memory Efficiency
2.1 Sparse Representation
2.2 Pruning Algorithm
3. Operations
3.1 Point Update
3.2 Query Occupied Voxels
3.3 Ray Casting
4. Implementation Classes
5. Related Documents
Design Documents
API Reference
6. References
Out-of-Core Tile Mapping Design
Overview
1. Architecture
2. Tile System
2.1 Tile Definition
2.2 Tile Contents
3. Storage Format
3.1 Directory Structure
3.2 IWLO Metadata Binary Format
3.3 Metadata JSON
4. LRU Cache
4.1 Cache Structure
4.2 Eviction Policy
4.3 Eviction Callback
5. Operations
5.1 Point Update Flow
5.2 Query Flow
5.3 Flush Operation
6. Implementation Classes
7. Mode Comparison
8. Related Documents
Design Documents
API Reference
Troubleshooting
Issue Log
[2025-11-27] C++ Backend Probability Fixed Value Bug
API Reference
Configuration Reference
Overview
Parameter Categories
Sonar Hardware
Filtering
Mounting
Voxel Map
IWLO Algorithm
Adaptive Scaling
Out-of-Core Storage
Crosstalk Filter
Robot Detection
Processing
Node-Only Parameters
Configuration Flow
Parameter Management System
ParameterDef
ParameterManager
Parameter Lists
Dynamic Parameter Updates
YAML Configuration Example
Related
3d_mapper.py
Overview
Architecture
Classes
SonarTo3DMapper
CrosstalkFilter
Core Methods
process_sonar_image
get_point_cloud
Utility Methods
IWLO Algorithm
Coordinate System
Usage Example
Related
3d_mapper_node.py
Overview
Architecture
Parameters
Dynamic Parameters
Registration
Supported Dynamic Parameters
Read-only Parameters (requires restart)
Example Usage
Topics
Input
Output (In-Memory Mode)
Output (Out-of-Core Mode)
Processing Flow
TF Broadcasting
Image Encoding
Mode Comparison
Usage
Related
mapper_backend.h
Overview
Class: IMapperBackend
Purpose
Implementations
Required API
Core Update
batch_update_iwlo
Parameter Configuration
set_iwlo_params
set_log_odds_params
set_intensity_params
set_adaptive_params
set_occupied_threshold
Query API
get_occupied_voxels
get_memory_usage
get_resolution
get_num_nodes
clear
Optional API
flush
preload_region
get_disk_usage
prune
supports_persistence
get_backend_type
Usage Example
Backend Comparison
Design Rationale
Related
probability_updater.cpp / .h
Overview
Architecture
Class: ProbabilityUpdater
Constructor
Configuration Methods
set_log_odds_params
set_adaptive_params
set_clamping_thresholds
set_intensity_params
set_iwlo_params
set_occupied_threshold
Core Update Method
batch_update_iwlo
Query Methods
get_occupied_voxels
get_memory_usage
get_num_nodes
get_resolution
get_observation_count
Maintenance Methods
prune_tree
clear
Synchronization Methods
set_incremental_sync
force_full_sync
Internal Implementation
Storage Strategy
Sync Strategies
Probability Conversion
Usage Example
Parameter Name Mapping
IMapperBackend Implementation
Backend Identity
Optional Methods
Related
outofcore_tile_mapper.cpp / .h
Overview
Architecture
Class: OutofcoreTileMapper
Constructor
ProbabilityUpdater Compatible API
batch_update_iwlo
Configuration Methods
Query Methods
get_occupied_voxels
get_all_occupied_voxels
get_memory_usage / get_num_nodes
Extended API
Region Query
Flush Operations
Merged OcTree
Tile Management
Preloading
Maintenance
Visualizer Notification
Internal Implementation
LRU Cache with Eviction Callback
Point Grouping
Thread Safety
ROS2 Parameter Mapping
Usage Example
Comparison: ProbabilityUpdater vs OutofcoreTileMapper
IMapperBackend Implementation
Backend Identity
Optional Methods
Related
iwlo_updater.cpp / .h
Overview
Class: IWLOUpdater
Purpose
Core Conversion Methods
log_odds_to_probability
probability_to_log_odds
IWLO Algorithm Methods
intensity_to_weight (explicit parameters)
intensity_to_weight (with IWLOParams)
compute_alpha (explicit parameters)
compute_alpha (with IWLOParams)
compute_adaptive_scale
compute_delta_log_odds
clamp_log_odds
Usage Example
Design Rationale
Related
voxel_storage.h
Overview
Class: VoxelStorage
Purpose
Interface Methods
Core Operations
get_log_odds
set_log_odds
get_observation_count
increment_observation_count
get_or_create_meta
Coordinate Operations
coord_to_key
key_to_coord
Query Operations
get_occupied_voxels
get_num_voxels
has_occupied_voxels
Persistence Operations
save
load
Maintenance Operations
clear
sync_to_octree
prune
get_memory_usage
OcTree Access
get_octree
Implementations
Data Types
IWLOMeta
OccupiedVoxel
Design Rationale
Related
octree_storage.cpp / .h
Overview
Architecture
Class: OctreeStorage
Constructor
Copy/Move Semantics
VoxelStorage Interface Implementation
Core Operations
Coordinate Operations
Query Operations
Persistence Operations
Maintenance Operations
Additional Methods
get_resolution
Dirty Flag Management
File Formats
octree.bt
iwlo_meta.bin
Usage Example
Design Rationale
Related
octree_mapper.cpp / .h
Overview
Architecture
Struct: MemoryStats
Class: OctreeMapper
Constructor
Update Methods
update_point
batch_update
batch_update_with_log_odds
insert_ray
Query Methods
get_occupied_voxels
get_memory_usage
get_num_nodes
get_resolution
Configuration Methods
set_probability_params
set_occupancy_thresholds
Maintenance Methods
prune_tree
clear
File I/O
save_to_file
load_from_file
Internal Implementation
SuppressOutput Class
Cache System
Point3d Hash
Dual Storage Rationale
Usage Example
Related
tile.cpp / .h
Overview
Data Structures
IWLOMeta
IWLOParams
TileIndex
OccupiedVoxel
Class: Tile
Constructor
IWLO Update Methods
update_voxel
batch_update
File I/O
save
load
IWLO Metadata File Format
Query Methods
get_occupied_voxels
has_occupied_voxels
Bounds
State Management
Maintenance
prune
clear
get_memory_usage
Internal Methods
sync_to_octree
Helper Functions
Storage Architecture
Disk Storage
Related
tile_manager.cpp / .h
Overview
Data Structures
MapMetadata
Class: TileManager
Constructor
initialize
Coordinate Conversion
world_to_tile_index
Path Management
get_tile_directory
tile_exists
Tile Enumeration
list_all_tiles
get_tiles_in_region
Metadata Management
save_metadata / load_metadata
update_bounds
Tile Operations
delete_tile
get_disk_usage
Getters
Directory Structure
Usage Example
Related
Utilities
Map Visualizer Node
Visualization Modes
Parameters
Topics
Tile Reload Strategy
Usage
C++ Python Bindings
Exposed Classes
Helper Structures
Module Info
Related
Sonar 3D Reconstruction
Index
Index