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:

```bash
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):

```bash
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:

```bash
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.