code/superpoint_ops/SUPERPOINT_STORY.md

Superpoint Story Views

What A Superpoint Is

A superpoint is a local over-segmentation unit in a point cloud: nearby points with similar geometric structure are grouped before the downstream network learns semantics.

This delivery bundle now uses segmentator as the default source and still supports three label sources:

• existing: the current superpoint.npy already stored with the dataset.
• segmentator: the PoVo-style reference logic, namely knn_graph(points, k=50) followed by segmentator.segment_point(points, normals, edges, kThresh=0.01, segMinVerts=20).
• canonical: the older voxel-plus-normal-bin deterministic fallback kept only for comparison.

What The Blender Views Mean

These are analysis images, not training-result images:

• Semantic-Family Superpoints: each superpoint inherits the hue family of its dominant semantic label, while neighboring superpoints in the same semantic region vary only in saturation/value.
• Superpoint Blocks: each superpoint gets a stable pseudo-random color.
• Superpoint Boundary: orange marks points whose local k-NN neighborhood mixes multiple superpoints strongly.
• Semantic Boundary: blue marks points whose local k-NN neighborhood mixes multiple semantic labels strongly.
• Boundary Relation: red = both boundaries, orange = superpoint-only, blue = semantic-only, white/gray = neither.
• Focus Superpoint: crops to one representative superpoint and shows its local shell.

How Boundary Handling Works

The boundary visualization is point-based rather than raster edge-based. For each sampled point, we look at its k nearest neighbors:

• if at least SP_BOUNDARY_RATIO of those neighbors belong to a different superpoint, the point is marked as a superpoint boundary point;
• if at least SEG_BOUNDARY_RATIO of those neighbors belong to a different semantic segment, the point is marked as a semantic boundary point.

This gives a boundary band in point-cloud space, which is much more stable than trying to draw a thin 2D line after projection.

White Background

White background is supported directly and is now the default theme for the bundle and the shell wrapper. The shell wrapper now also defaults to SOURCE=segmentator and writes into outputs/superpoint_delivery/story_segmentator_white. Use BACKGROUND_THEME=white in the shell wrapper or --background_theme white in the Python entrypoint.

Commands

Generate PoVo-style segmentator labels without overwriting dataset files:

cd /mnt/data/AODUOLI/PAMI2026
python3 superpoint_delivery_bundle.py generate \
  --room Area_1/office_1 \
  --output_root /mnt/data/AODUOLI/PAMI2026/outputs/superpoint_delivery/generated_segmentator

Render white-background story views from the reference-method labels (default behavior, now including the semantic-family view first):

cd /mnt/data/AODUOLI/PAMI2026
bash run_blender_superpoint_story.sh

Render white-background story views from the current dataset labels only when you explicitly need that comparison:

cd /mnt/data/AODUOLI/PAMI2026
SOURCE=existing BACKGROUND_THEME=white OUT_ROOT=/mnt/data/AODUOLI/PAMI2026/outputs/superpoint_delivery/story_existing_white bash run_blender_superpoint_story.sh

Output Layout

Outputs are written under the chosen output root, for example:

• /mnt/data/AODUOLI/PAMI2026/outputs/superpoint_delivery/story_segmentator_white/<room_tag>/
• /mnt/data/AODUOLI/PAMI2026/outputs/superpoint_delivery/<variant>/<room_tag>/

Each room contains:

• individual PNGs for the analysis views;
• *_story_grid.png as a contact sheet;
• assets/*.npz Blender-ready render assets;
• *_summary.json with the sampled statistics and boundary counts.