code/superpoint_ops/SUPERPOINT.md

S3DIS Superpoints - Current Project Contract

Canonical Definition

• Algorithm: voxelize point coordinates, append binned normals when normal.npy exists, then run np.unique(..., return_inverse=True) on the tokenized rows to obtain per-point superpoint ids (int32).
• Default hyperparameters: voxel_size = 0.12, normal_bins = 8.
• Canonical generator: PAMI2026/scripts/generate_s3dis_superpoints.py, consistent with pointcept_framework/scripts/visualize_s3dis_superpoints.py.
• Authoritative training tree: Haozhe2:/map-vepfs/haozhe/PAMI_superpoint/pointcept_framework. The poplab mirror at /mnt/data/AODUOLI/_work_biptv3/pointcept_framework should stay aligned with it.

Relation To Historical Data

• Historical superpoint.npy files used by earlier Haozhe2 / local runs may not be byte-identical to the canonical 0.12 / 8 generator.
• If paper claims and experiments must be fully self-consistent, regenerate the whole dataset with --write, sync the refreshed superpoint.npy, and retrain from those new files.
• If retraining is deferred, keep using the current on-disk superpoint.npy for both training and visualization, and do not mix regenerated visualizations with old training checkpoints without calling it out explicitly.

Canonical Training Entry

• Submit from poplab through /mnt/data/AODUOLI/PAMI2026/run.py.
• Default follow-up config: configs/s3dis/semseg-pt-v3m1-0-rpe_sp_after_pool_reboot.py.
• 4-GPU reboot override preset: configs/s3dis/reboot_override.py.
• Resume-style overrides should go through MLP_OPTIONS, for example: MLP_OPTIONS=\"resume=True weight=exp/.../model/model_last.pth\".
• Do not copy the PAMI2026 tree onto Haozhe2. Keep Haozhe2 compute-only under /map-vepfs/haozhe/PAMI_superpoint/....
• If you need a Haozhe-side launcher file, render it from run.py; the generated file contains only Haozhe paths.

Commands

cd /mnt/data/AODUOLI/PAMI2026

# Preview only
python3 run.py

# Preview the current 4-GPU superpoint reboot launch
MLP_NUM_GPUS=4 \
MLP_CUDA_VISIBLE_DEVICES=0,1,2,3 \
MLP_CONFIG=configs/s3dis/reboot_override.py \
python3 run.py

# Render a Haozhe-local launcher without exposing poplab paths
MLP_RENDER_HAOZHE=1 \
MLP_CONFIG=configs/s3dis/reboot_override.py \
MLP_HAOZHE_LAUNCHER_OUT=outputs/run_training_haozhe.py \
python3 run.py

# Switch to another config / save_path
MLP_CONFIG=configs/nuscenes/semseg-pt-v3m1-0-base_nusc.py \
MLP_SAVE_PATH=exp/nuscenes/semseg-pt-v3m1-0-base_nusc_occfix \
python3 run.py

# Real submit with resume overrides
export VOLC_AK=... VOLC_SK=...
MLP_SUBMIT=1 \
MLP_NUM_GPUS=4 \
MLP_CUDA_VISIBLE_DEVICES=0,1,2,3 \
MLP_OPTIONS="resume=True weight=exp/s3dis/.../model/model_last.pth" \
python3 run.py

# Inspect or rewrite superpoints
python scripts/generate_s3dis_superpoints.py
python scripts/generate_s3dis_superpoints.py --write
python scripts/generate_s3dis_superpoints.py --room Area_1/office_1 --write

# Safe candidate generation for visualization-only comparison
python scripts/generate_s3dis_superpoints.py --room Area_1/office_1 --write \
  --output_root outputs/superpoint_candidates/canonical_v012_n8

Visualization

• Mitsuba single-file entry: superpoint_visualize_s3dis.py (reads on-disk superpoint.npy, same as Haozhe2 when data is synced).
• Batch (recommended): run_haozhe2_match_superpoint_vis.sh — env toggles DO_MITSUBA, DO_MITSUBA_PERCLASS, DO_BLENDER; optional FILM, SPP, MAXP, ROOMS, DATA_ROOT, PERCLASS_ROOM.
• Example: full Mitsuba for five rooms + Blender + per-class HQ for office_1:

cd /mnt/data/AODUOLI/PAMI2026
# 默认：Mitsuba 五场景整景 +（可按需再开 per-class / Blender）
bash run_haozhe2_match_superpoint_vis.sh
# 仅按类 HQ（office_1），可调 SPP 加速
DO_MITSUBA=0 DO_MITSUBA_PERCLASS=1 DO_BLENDER=0 SPP=128 bash run_haozhe2_match_superpoint_vis.sh

# Compare a candidate label file without touching room/superpoint.npy
LABEL_NPY=/mnt/data/AODUOLI/PAMI2026/outputs/superpoint_candidates/canonical_v012_n8/Area_1/office_1/superpoint.npy \
LABEL_TAG=canonical_v012_n8 \
ROOMS=office_1 DO_MITSUBA=1 DO_BLENDER=1 DO_MITSUBA_PERCLASS=0 \
bash run_haozhe2_match_superpoint_vis.sh

• Long Mitsuba runs log to logs/per_class_hq_latest.log when using tee manually.
• This is unrelated to the 2D image-network model named SuperPoint.