Dear ImGui selectable octree grid viewer

_ImGUIselectableOctGrid is a lightweight viewer module for OpenKAI 3D geometry streams. It derives from _GeometryViewerBase, copies geometry from PCLframe and LineFrame DataObjects and _SelectableOctGrid::get(OCTGRID_CELLS*) cell snapshots, and renders through Dear ImGui without using Open3D viewer APIs.

The viewer lives in src/UI/Viewer/ImGUI/: _ImGUIselectableOctGrid.* implements the module, ImGUIbackend.* handles the window/input backend, and ImGUIglRenderer.* renders its geometry with OpenGL. Its name matches the _SelectableOctGrid backend module and the browser viewer _WebSelectableOctGrid.

Dear ImGui Install

Dear ImGui is normally consumed directly from source. The recommended setup is to clone it once and pass its source root to OpenKAI with IMGUI_DIR.

Clone Dear ImGui:

git clone --depth 1 https://github.com/ocornut/imgui.git

For Ubuntu desktop with GLFW/OpenGL:

sudo apt-get update
sudo apt-get install libglfw3-dev libgl1-mesa-dev

cd OpenKAI/build
cmake \
  -DWITH_UNIVERSE=ON \
  -DUSE_IMGUI=ON \
  -DIMGUI_DIR=$HOME/dev/imgui \
  -DIMGUI_BACKEND=GLFW \
  -DIMGUI_RENDERER=OPENGL \
  ../
make -j$(nproc)

For Raspberry Pi / embedded Linux with SDL2/OpenGL ES:

sudo apt-get update
sudo apt-get install libsdl2-dev libgles2-mesa-dev

cd OpenKAI/build
cmake \
  -DWITH_UNIVERSE=ON \
  -DUSE_IMGUI=ON \
  -DIMGUI_DIR=$HOME/dev/imgui \
  -DIMGUI_BACKEND=SDL2 \
  -DIMGUI_RENDERER=OPENGLES \
  ../
make -j$(nproc)

Build Options

The viewer is optional and is enabled with:

mkdir -p build
cd build
cmake \
  -DWITH_UNIVERSE=ON \
  -DUSE_IMGUI=ON \
  -DIMGUI_DIR=/path/to/imgui \
  -DIMGUI_BACKEND=GLFW \
  -DIMGUI_RENDERER=OPENGL \
  ../
make -j$(nproc)

USE_OPEN3D is not required for the viewer or _PCLfile PLY input. Optional Open3D-backed processing and registration modules remain separate.

When using IMGUI_DIR, OpenKAI compiles ImGui and the selected backend sources directly. When using IMGUI_INCLUDE_DIR and IMGUI_LIBRARIES, OpenKAI links the core ImGui library and compiles backend sources if their .cpp files are available in IMGUI_BACKENDS_DIR.

Available backend options:

Option	Values	Notes
IMGUI_BACKEND	GLFW, SDL2	Window/input backend. GLFW is a good Ubuntu desktop default. SDL2 is useful on embedded Linux images where SDL is already integrated.
IMGUI_RENDERER	OPENGL, OPENGLES	OPENGL targets desktop GL. OPENGLES targets OpenGL ES 3 style contexts, usually better for Raspberry Pi and embedded GPUs.
IMGUI_DIR	path	Dear ImGui source root containing imgui.cpp and backends/. This is the recommended setup.
IMGUI_INCLUDE_DIR	path	Alternative include directory when using a packaged/prebuilt ImGui.
IMGUI_BACKENDS_DIR	path	Alternative backend include/source directory when using a packaged/prebuilt ImGui.
IMGUI_LIBRARIES	libraries	Optional prebuilt ImGui library or libraries. If omitted and IMGUI_DIR is set, OpenKAI compiles the ImGui source files directly.

Module Config

Use the class name _ImGUIselectableOctGrid in JSON:

{
  "viewer": {
    "class": "_ImGUIselectableOctGrid",
    "vWinSize": [1280, 720],
    "bShowPanel": true,
    "bShowGrid": true,
    "camFov": 70.0,
    "vCamLookAt": [0.0, 0.0, 0.0],
    "vCamEye": [0.0, -8.0, 4.0],
    "vCamUp": [0.0, 0.0, 1.0],
    "thread": {
      "FPS": 30
    },
    "threadUI": {
      "FPS": 60
    },
    "vGeometry": [
      {
        "PCLframeIn": "lidar_points",
        "nP": 200000,
        "matPointSize": 2,
        "matCol": [1.0, 1.0, 1.0]
      }
    ],
    "vSelectableOctGrid": [
      {
        "_SelectableOctGrid": "occupancy_grid",
        "nC": 100000,
        "matLineWidth": 1,
        "matCol": [0.3, 0.8, 1.0]
      }
    ]
  }
}

vGeometry entries name PCLframe and/or LineFrame DataObjects through PCLframeIn and LineFrameIn. vSelectableOctGrid accepts only _SelectableOctGrid sources for cell streams. The viewer stores these in separate typed lists. Render snapshots contain only shared immutable draw assets, with no producer module pointers. Point/line conversion is cached per input timestamp and expiry boundary, so unchanged geometry is retained across UI frames. Source vectors are copied with get when getTstamp() changes. Empty publications with changed timestamps clear prior geometry; repeated timestamps cannot signal updates. Source configuration and limits are shared with the web viewer.

The old source name lists and generic reference-frame entries are removed. Per-source caps use nP, nL, and nC; zero disables that output. Octree grids have no point/line output API. Their vPCLframesIn setting lists point-cloud DataObject names.

Sample PLY Test

jsonCfg/ImGUI.json is configured to load:

data/PointCloud/StanfordBunny/bun000.ply

This sample uses _PCLfile for PLY file I/O and publishes an independent PCLframe. The sample and runtime point/line viewers work without Open3D. The sample is bun000.ply, a 1.9 MB Stanford Bunny range scan mirror from the University of New Mexico public directory:

curl -L https://www.cs.unm.edu/~angel/TEST/CODE/Code/BUNNY/data/bun000.ply \
  -o data/PointCloud/StanfordBunny/bun000.ply

Run the viewer from the repository root so the relative PLY path resolves:

./build/OpenKAI jsonCfg/ImGUI.json

Controls

• Left drag: orbit camera.
• Right or middle drag: pan.
• Mouse wheel: zoom.
• Reset camera: restore configured camera pose.
• Auto bound: fit the camera to the current geometry snapshot.

Notes

Point size and line width are viewer/material settings (matPointSize, matLineWidth, pointScale, and lineScale); individual GEOMETRY_POINT and GEOMETRY_LINE records only carry geometry, color, and timestamp data.

Point and line colors use Vector3f RGB in geometry records, viewer snapshots, and GPU buffers. Both GPU and CPU rendering keep them opaque; matCol supplies only their fallback RGB. PLY alpha properties and packed rgba alpha bytes are ignored. Occupied cells retain Vector4f RGBA and multiply cell alpha by matCol[3]: alpha 0 is invisible, 1 is opaque, and intermediate values blend.

When OpenGL or OpenGL ES rendering is enabled, the viewer uploads point and line snapshots into GPU buffers and renders them from an ImGui callback. The CPU draw-list path remains available as a fallback for backends without GL support.

Occupied octree cells

The grid publishes a root center/size/depth/timestamp header plus 20-byte records (16-byte ID and RGBA8). ImGui decodes each ID into an IMGUI_VIEWER_BOX, retaining its UUID, center, full size, and color for future picking. The GPU renderer and CPU fallback generate the twelve edges from those boxes. Camera fitting, visibility, line width, and object opacity apply to grid boxes too.

Use grid nMaxCells to cap occupied cells (default 8333). nMaxLines is no longer accepted. Viewer nCbuf defaults to 100000; per-object vSelectableOctGrid[].nC can lower it, and zero omits cells. Point and line limits continue to control their own primitives. All occupied levels are included. Cell colors come from averaged point RGB with initial alpha 1 unless vColCellOcc explicitly supplies a uniform [r,g,b,a] override (a three-component override defaults to alpha 1). Empty or expired snapshots clear the previous boxes.

See the cell format and tests for ID layout, snapshot semantics, and verification commands.

The viewer accepts nPbuf: 0 and/or nLbuf: 0 to disable collection of those types. Compact cell collection continues independently, allowing a cells-only viewer without collecting point or line snapshots.