SIGGRAPH OctoMap Ingest

Starter project for converting the Sojourner mission package flight map into an OctoMap occupancy tree.

The source package is expected at:

/Users/bwoodard/Downloads/7f8eb141-3486-4b39-a546-eb98c47ba351-fixed-package

The flight map format is documented in the package README:

• flightmap/flightmap.bin: one byte per voxel, x-major layout
• 0: unknown, left absent in the OctoMap
• 1: free, inserted as free space
• 2: occupied, inserted as occupied space
• 3: sky, ignored by default and optionally inserted as free

Build

cmake -S . -B build
cmake --build build --parallel

The CMake project first tries find_package(octomap CONFIG). If OctoMap is not installed, it fetches OctoMap v1.10.0 and builds the core library.

Run

./build/flightmap_to_octomap \
  --package /Users/bwoodard/Downloads/7f8eb141-3486-4b39-a546-eb98c47ba351-fixed-package \
  --output output/world_octomap.ot

To treat SKY voxels as free space:

./build/flightmap_to_octomap \
  --package /Users/bwoodard/Downloads/7f8eb141-3486-4b39-a546-eb98c47ba351-fixed-package \
  --output output/world_octomap_with_sky.ot \
  --include-sky-as-free

To print a labeled 2D voxel slice while converting:

./build/flightmap_to_octomap \
  --package /Users/bwoodard/Downloads/7f8eb141-3486-4b39-a546-eb98c47ba351-fixed-package \
  --print-slice y 24 \
  --slice-window 40

Slice labels:

• ?: unknown
• .: free
• #: occupied
• ^: sky
• !: invalid/unexpected class byte

For --print-slice y 24, rows are z high to low and columns are x left to right, giving a top-down view at grid layer y=24.

To print a small 3D cube as stacked top-down layers:

./build/flightmap_to_octomap \
  --package /Users/bwoodard/Downloads/7f8eb141-3486-4b39-a546-eb98c47ba351-fixed-package \
  --print-cube 137 24 162 12

The cube arguments are center-x center-y center-z size in grid coordinates. Each printed layer is one y height, with rows as z high to low and columns as x left to right.

To create a simple rotatable 3D browser viewer for the same cube:

./build/flightmap_to_octomap \
  --package /Users/bwoodard/Downloads/7f8eb141-3486-4b39-a546-eb98c47ba351-fixed-package \
  --print-cube 137 24 162 24 \
  --pathfinder astar \
  --drone-altitude-m 4.0 \
  --export-cube-html output/voxel_cube_viewer.html

Open output/voxel_cube_viewer.html in a browser. The viewer is a self-contained HTML file, so it does not require Qt, OpenGL, or a separate GUI dependency. Drag the canvas to rotate the cube, use the class checkboxes to hide/show labels, and use the y clipping sliders to isolate a layer range. The path is drawn in yellow. The pathfinder dropdown can recompute A* or Dijkstra inside normal cube-sized exports.

To set exact planner endpoints:

./build/flightmap_to_octomap \
  --package /Users/bwoodard/Downloads/7f8eb141-3486-4b39-a546-eb98c47ba351-fixed-package \
  --print-cube 150 22 310 20 \
  --pathfinder dijkstra \
  --path-start 141 24 300 \
  --path-goal 159 24 317 \
  --export-cube-html output/voxel_cube_viewer.html

To export the full flightmap into the viewer instead of a small cube:

./build/flightmap_to_octomap \
  --package /Users/bwoodard/Downloads/7f8eb141-3486-4b39-a546-eb98c47ba351-fixed-package \
  --viewer-full-map \
  --export-cube-html output/full_map_viewer.html

To export exactly one quarter of the map footprint, use --viewer-quarter-map. The quarter keeps all y altitude layers, but uses half the x range and half the z range:

./build/flightmap_to_octomap \
  --package /Users/bwoodard/Downloads/7f8eb141-3486-4b39-a546-eb98c47ba351-fixed-package \
  --viewer-quarter-map 0 \
  --pathfinder astar \
  --drone-altitude-m 4.0 \
  --export-cube-html output/quarter_map_viewer.html

Quarter indices are 0..3, moving across the low/high halves of x and z. If no explicit start/goal is provided, the tool chooses a long route inside the largest connected FREE component in the exported bounds.

To export one sixteenth of the original map footprint, use --viewer-sixteenth-map. This keeps all y altitude layers, but uses one quarter of x and one quarter of z:

./build/flightmap_to_octomap \
  --package /Users/bwoodard/Downloads/7f8eb141-3486-4b39-a546-eb98c47ba351-fixed-package \
  --viewer-sixteenth-map 0 \
  --viewer-padding 6 \
  --pathfinder astar \
  --drone-altitude-m 4.0 \
  --export-cube-html output/sixteenth_map_viewer.html

Sixteenth indices are 0..15, ordered across four x segments for each of four z segments. --viewer-padding adds context around the selected tile so paths near a tile boundary do not look visually clipped.

Full-map HTML exports load millions of voxels, so the viewer uses a render-budget slider and samples non-path voxels for interactivity. The generated viewer prefers WebGPU rendering and falls back to Canvas 2D if WebGPU is unavailable. For pathfinding, prefer explicit start/goal points in the same free-space component; navgraph.json reports many disconnected free components. If no start/goal is provided, the tool searches the selected bounds for the largest connected FREE component and picks two distant endpoints inside it.

On Apple Silicon, WebGPU is the preferred browser rendering path for this debugger. OpenGL works for many native tools, but it is deprecated on macOS and is not ideal for new visualization work.

--drone-altitude-m is a world-y value in meters. The current default 4.0 is only a placeholder cruising altitude for debugging; choose this deliberately for your drone model.

The run writes:

• output/world_octomap.ot: OctoMap binary tree
• output/ingest-summary.json: observed class counts and conversion metadata

Data Notes

The package reports a 274 x 48 x 325 grid with 1 m voxels and origin (-179.0189666748047, -20.218748092651367, -178.12062072753906).

navgraph.json says the graph semantics are 6-connected FREE voxels; it is not a separate edge list. The largest free component has 645549 voxels, and frontier voxels are FREE cells adjacent to UNKNOWN.