Patchwork: Z-up axis transform, per-patch (zone × ring × sector) color, VLP-16 global Z hard cap

ensureZUp(cloud, presetId) flips Z for NaverLabs (PCD ships Z-down with
floor mass at z ≈ +0.6); KITTI is already Z-up. Both Patchwork and
TRAVEL pages now run the transform before invoking their algorithms.
Without this, the indoor scan's ceiling sat at the bottom of the
sensor frame and the ground gate had nothing to catch.

Region coloring: regionId now packs (zone, ring, sector); regionColor()
walks zones × rings × sectors so every CZM patch gets its own
golden-angle hue. Previously all sectors within a (zone, ring) shared
one color and visually read as concentric rings rather than patches.

VLP-16 hard cap: applies the global elevation threshold (0.0 in sensor
frame) as a defensive gate even on inner rings. Without this, a flat
ceiling could squeak past the FLAT_ENOUGH override on inner rings and
get marked as ground. HDL-64's useGlobalElevation=false so this is a
no-op there.

Smoke verification on the actual presets:
  NaverLabs (Z-flipped): 27% ground, 81 patches across 7 rings,
                         ground z p50 = -0.40 (sensor h = 0.6)
  KITTI:                 59% ground, 230 patches across 15 rings,
                         ground z p50 = -1.77 (sensor h = 1.723)

Author: LimHyungTae

web/scripts/inspect-axes.mjs

@@ -0,0 +1,56 @@
+// Quick axis-orientation check on the bundled presets — prints per-axis
+// percentile ranges so we can decide which axis is "up" for each sensor.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+const { parseFromBuffer } = await import("../src/lib/pcd.ts");
+
+async function dump(label, relPath) {
+  const buf = readFileSync(resolve(relPath));
+  const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  const c = parseFromBuffer(ab, relPath);
+  const N = c.count;
+  const xs = new Float32Array(N), ys = new Float32Array(N), zs = new Float32Array(N);
+  for (let i = 0; i < N; i++) {
+    xs[i] = c.positions[3 * i];
+    ys[i] = c.positions[3 * i + 1];
+    zs[i] = c.positions[3 * i + 2];
+  }
+  const sortedX = xs.slice().sort();
+  const sortedY = ys.slice().sort();
+  const sortedZ = zs.slice().sort();
+  const pct = (a, p) => a[Math.min(a.length - 1, Math.max(0, Math.floor(p * a.length)))];
+  console.log(`\n=== ${label} (${N} pts) ===`);
+  console.log(
+    `  X: p1=${pct(sortedX, 0.01).toFixed(2)}  p50=${pct(sortedX, 0.5).toFixed(2)}  p99=${pct(sortedX, 0.99).toFixed(2)}`,
+  );
+  console.log(
+    `  Y: p1=${pct(sortedY, 0.01).toFixed(2)}  p50=${pct(sortedY, 0.5).toFixed(2)}  p99=${pct(sortedY, 0.99).toFixed(2)}`,
+  );
+  console.log(
+    `  Z: p1=${pct(sortedZ, 0.01).toFixed(2)}  p50=${pct(sortedZ, 0.5).toFixed(2)}  p99=${pct(sortedZ, 0.99).toFixed(2)}`,
+  );
+  // Histogram of each axis to see which one has a clear "ground" (a heavy
+  // mass at one extreme).
+  for (const [name, arr] of [["X", sortedX], ["Y", sortedY], ["Z", sortedZ]]) {
+    const lo = arr[0],
+      hi = arr[arr.length - 1];
+    const span = hi - lo || 1;
+    const bins = new Array(10).fill(0);
+    for (let i = 0; i < N; i++) {
+      const v = arr[i];
+      const b = Math.min(9, Math.floor(((v - lo) / span) * 10));
+      bins[b]++;
+    }
+    const max = Math.max(...bins);
+    const bar = (n) => "█".repeat(Math.round((n / max) * 18)) || "·";
+    console.log(`  ${name} hist:`);
+    for (let i = 0; i < 10; i++) {
+      const lov = (lo + (span * i) / 10).toFixed(2).padStart(7);
+      const hiv = (lo + (span * (i + 1)) / 10).toFixed(2).padStart(7);
+      console.log(`    [${lov}, ${hiv}] ${bar(bins[i])} ${bins[i]}`);
+    }
+  }
+}
+
+await dump("NaverLabs VLP-16", "public/data/naverlabs_vel16.pcd");
+await dump("KITTI HDL-64", "public/data/kitti00_000000.bin");

web/scripts/smoke-presets.mjs

@@ -0,0 +1,60 @@
+// Smoke test on the actual bundled preset PCDs — confirms that after the
+// per-preset ensureZUp transform, Patchwork finds reasonable ground and
+// produces many distinct patches.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const { parseFromBuffer } = await import("../src/lib/pcd.ts");
+const { runPatchwork, unpackPatch } = await import("../src/lib/filters/patchwork.ts");
+const { ensureZUp } = await import("../src/lib/axisTransform.ts");
+const { SENSOR_VLP16, SENSOR_HDL64 } = await import("../src/lib/sensorConfig.ts");
+
+function loadLocal(relPath) {
+  const buf = readFileSync(resolve(relPath));
+  const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  return parseFromBuffer(ab, relPath);
+}
+
+function summarize(label, result) {
+  const groundN = result.groundCloud.count;
+  const ngN = result.nonGroundCloud.count;
+  const total = groundN + ngN;
+  const ratio = total === 0 ? 0 : groundN / total;
+  const sectorsPresent = new Set();
+  for (let i = 0; i < result.groundRegionIds.length; i++) {
+    sectorsPresent.add(result.groundRegionIds[i]);
+  }
+  // How many distinct sectors per (zone, ring)?
+  const ringKeys = new Set();
+  for (const rid of sectorsPresent) {
+    const { zone, ring } = unpackPatch(rid);
+    ringKeys.add(`${zone}-${ring}`);
+  }
+
+  console.log(`\n=== ${label} ===`);
+  console.log(`  ground / total: ${groundN.toLocaleString()} / ${total.toLocaleString()} (${(100 * ratio).toFixed(1)}%)`);
+  console.log(`  patches with ground: ${sectorsPresent.size} (across ${ringKeys.size} distinct rings)`);
+  // Show ground z-band distribution.
+  const zs = [];
+  for (let i = 0; i < groundN; i++) {
+    zs.push(result.groundCloud.positions[3 * i + 2]);
+  }
+  zs.sort((a, b) => a - b);
+  if (zs.length > 0) {
+    const p = (q) => zs[Math.min(zs.length - 1, Math.max(0, Math.floor(q * zs.length)))];
+    console.log(
+      `  ground z: p1=${p(0.01).toFixed(2)}  p50=${p(0.5).toFixed(2)}  p99=${p(0.99).toFixed(2)}`,
+    );
+  }
+}
+
+const naverRaw = loadLocal("public/data/naverlabs_vel16.pcd");
+console.log(`NaverLabs raw z range: [${naverRaw.bbox.min[2].toFixed(2)}, ${naverRaw.bbox.max[2].toFixed(2)}]`);
+const naverFlipped = ensureZUp(naverRaw, "naverlabs");
+console.log(`NaverLabs flipped z range: [${naverFlipped.bbox.min[2].toFixed(2)}, ${naverFlipped.bbox.max[2].toFixed(2)}]`);
+summarize("NaverLabs VLP-16 (Z flipped)", runPatchwork(naverFlipped, SENSOR_VLP16));
+
+const kittiRaw = loadLocal("public/data/kitti00_000000.bin");
+console.log(`KITTI raw z range: [${kittiRaw.bbox.min[2].toFixed(2)}, ${kittiRaw.bbox.max[2].toFixed(2)}]`);
+const kittiZup = ensureZUp(kittiRaw, "kitti");
+summarize("KITTI HDL-64 (no flip)", runPatchwork(kittiZup, SENSOR_HDL64));

web/src/lib/axisTransform.ts

@@ -0,0 +1,26 @@
+import { cloudFromPositions, type PointCloud } from "./types";
+
+/**
+ * Patchwork and TRAVEL both assume the LiDAR cloud is given in a Z-up frame
+ * (sensor at z = +sensor_height above the floor, gravity along -Z). Some
+ * preset datasets ship in different conventions:
+ *
+ *   - KITTI HDL-64: Z-up already (X forward, Y left, Z up).
+ *   - NaverLabs VLP-16 PCD: Z-down (floor mass sits at z ≈ +0.6, ceiling at
+ *     large negative z) — needs Z to be flipped before either algorithm
+ *     will produce meaningful ground / cluster output.
+ *
+ * Custom user uploads are disabled on the Patchwork / TRAVEL chapters, so
+ * a small per-preset switch is enough.
+ */
+export function ensureZUp(cloud: PointCloud, presetId: string): PointCloud {
+  if (presetId !== "naverlabs") return cloud;
+  const N = cloud.count;
+  const out = new Float32Array(N * 3);
+  for (let i = 0; i < N; i++) {
+    out[3 * i] = cloud.positions[3 * i];
+    out[3 * i + 1] = cloud.positions[3 * i + 1];
+    out[3 * i + 2] = -cloud.positions[3 * i + 2];
+  }
+  return cloudFromPositions(out);
+}

web/src/lib/filters/patchwork.ts

@@ -115,7 +115,7 @@ export function runPatchwork(
     pointZone[i] = zone;
     pointRing[i] = ring;
     pointSector[i] = sector;
-    regionId[i] = zone * 100 + ring;
+    regionId[i] = packPatch(zone, ring, sector);
 
     // Pack bin key as zone × 1e6 + ring × 1e3 + sector — fits in 32 bits.
     const key = zone * 1_000_000 + ring * 1_000 + sector;
@@ -267,6 +267,15 @@ export function runPatchwork(
       acceptAsGround = !(c.useGlobalElevation && centroidZ > c.globalElevationThr);
     }
 
+    // Defensive hard cap: when useGlobalElevation is on (e.g. indoor
+    // sensors like VLP-16), reject anything above the global threshold even
+    // if it slipped through the inner-ring FLAT_ENOUGH override. This is
+    // what reliably keeps ceilings and high horizontal surfaces out on
+    // indoor scans.
+    if (acceptAsGround && c.useGlobalElevation && centroidZ > c.globalElevationThr) {
+      acceptAsGround = false;
+    }
+
     if (!acceptAsGround) continue;
 
     for (const i of curSeeds) isGround[i] = 1;
@@ -312,16 +321,54 @@ export function runPatchwork(
   };
 }
 
-/** Pack (zone, ring) → stable color via the golden-angle hue spiral.
- *  Note: three.js's Color parser needs the comma-separated hsl() form. */
-export function regionColor(zone: number, ring: number, czm: CzmConfig): string {
-  const totalRingsBefore = czm.numRingsPerZone
-    .slice(0, zone)
-    .reduce((a, b) => a + b, 0);
-  const idx = totalRingsBefore + ring;
+/** Pack (zone, ring, sector) into a single 32-bit-safe integer:
+ *    zone × 1_000_000 + ring × 1_000 + sector.
+ *  Sectors max out at 56 (HDL-64 zone 2), rings at 5 (HDL-64 zone 3),
+ *  zones at 4 — all fit comfortably. */
+export function packPatch(zone: number, ring: number, sector: number): number {
+  return zone * 1_000_000 + ring * 1_000 + sector;
+}
+
+export function unpackPatch(rid: number): { zone: number; ring: number; sector: number } {
+  if (rid < 0) return { zone: -1, ring: -1, sector: -1 };
+  const zone = Math.floor(rid / 1_000_000);
+  const r2 = rid - zone * 1_000_000;
+  const ring = Math.floor(r2 / 1_000);
+  const sector = r2 - ring * 1_000;
+  return { zone, ring, sector };
+}
+
+/** Compute the global patch index — i.e. how many patches come before this
+ *  one when iterating zones × rings × sectors in order. Used to assign a
+ *  golden-angle hue to every (zone, ring, sector) bin so each Patchwork
+ *  region is visibly distinct in the viewer. */
+export function globalPatchIndex(
+  zone: number,
+  ring: number,
+  sector: number,
+  czm: CzmConfig,
+): number {
+  let idx = 0;
+  for (let z = 0; z < zone; z++) {
+    idx += czm.numRingsPerZone[z] * czm.numSectorsPerZone[z];
+  }
+  idx += ring * czm.numSectorsPerZone[zone] + sector;
+  return idx;
+}
+
+/** Stable per-region color via the golden-angle hue spiral.
+ *  Note: three.js's Color parser only matches the comma-separated hsl() form. */
+export function regionColor(
+  zone: number,
+  ring: number,
+  sector: number,
+  czm: CzmConfig,
+): string {
+  const idx = globalPatchIndex(zone, ring, sector, czm);
   const hue = (idx * 137.508) % 360;
-  // Outer zones get slightly desaturated to keep the palette cohesive.
-  const sat = 78 - zone * 4;
+  // Tiny zone-driven shading so the four CZM zones still read at a glance
+  // even amid the per-patch hue scatter.
+  const sat = 78 - zone * 3;
   const lit = 60 - zone * 2;
   return `hsl(${hue.toFixed(0)}, ${sat}%, ${lit}%)`;
 }

web/src/pages/Extra03Patchwork.tsx

@@ -8,7 +8,8 @@ import DemoAbout from "../components/DemoAbout";
 import DemoParams from "../components/DemoParams";
 import PointCloudViewer from "../components/PointCloudViewer";
 import { useT } from "../i18n";
-import { regionColor, runPatchwork } from "../lib/filters/patchwork";
+import { regionColor, runPatchwork, unpackPatch } from "../lib/filters/patchwork";
+import { ensureZUp } from "../lib/axisTransform";
 import { SENSOR_BY_PRESET, type SensorConfig } from "../lib/sensorConfig";
 import { emptyCloud, type PointCloud } from "../lib/types";
 
@@ -22,22 +23,25 @@ export default function Extra03Patchwork() {
   const [presetId, setPresetId] = useState<PresetId>("kitti");
   const sensor: SensorConfig | null = SENSOR_BY_PRESET[presetId] ?? null;
 
+  // Patchwork assumes Z-up; some presets (NaverLabs) ship Z-down.
+  // ensureZUp normalizes per-preset before we run the algorithm.
+  const zUpCloud = useMemo(() => ensureZUp(raw, presetId), [raw, presetId]);
+
   const result = useMemo(() => {
-    if (!sensor || raw.count === 0) return null;
-    return runPatchwork(raw, sensor);
-  }, [raw, sensor]);
+    if (!sensor || zUpCloud.count === 0) return null;
+    return runPatchwork(zUpCloud, sensor);
+  }, [zUpCloud, sensor]);
 
-  // Per-vertex color buffer for the ground cloud — every point gets its
-  // (zone, ring) region color so adjacent CZM bins are clearly visible.
+  // Per-vertex color buffer for the ground cloud — every point gets a
+  // unique (zone, ring, sector) patch color so individual CZM patches are
+  // distinguishable, not just rings.
   const groundColors = useMemo(() => {
     if (!result || !sensor) return new Float32Array(0);
     const tmp = new THREE.Color();
     const out = new Float32Array(result.groundCloud.count * 3);
     for (let i = 0; i < result.groundCloud.count; i++) {
-      const rid = result.groundRegionIds[i];
-      const zone = Math.floor(rid / 100);
-      const ring = rid - zone * 100;
-      tmp.setStyle(regionColor(zone, ring, sensor.czm));
+      const { zone, ring, sector } = unpackPatch(result.groundRegionIds[i]);
+      tmp.setStyle(regionColor(zone, ring, sector, sensor.czm));
       out[i * 3] = tmp.r;
       out[i * 3 + 1] = tmp.g;
       out[i * 3 + 2] = tmp.b;
@@ -47,7 +51,7 @@ export default function Extra03Patchwork() {
 
   const groundCount = result?.groundCloud.count ?? 0;
   const nonGroundCount = result?.nonGroundCloud.count ?? 0;
-  const numRegions = result?.uniqueRegions.length ?? 0;
+  const numPatches = result?.uniqueRegions.length ?? 0;
 
   const layers = useMemo(() => {
     if (!result || !sensor) return [];
@@ -80,7 +84,7 @@ export default function Extra03Patchwork() {
               </span>
               <span className="text-[var(--mut)]">·</span>
               <span>
-                <span className="text-[var(--text-strong)]">{numRegions}</span> regions
+                <span className="text-[var(--text-strong)]">{numPatches}</span> patches
               </span>
             </div>
             <span className="code-font text-[var(--dim)]">

web/src/pages/Extra04Travel.tsx

@@ -10,6 +10,7 @@ import RangeImageView from "../components/RangeImageView";
 import { useT } from "../i18n";
 import { ClusterColorMatcher, type Cluster } from "../lib/filters/euclideanCluster";
 import { runTravel, travelClusterColor } from "../lib/filters/travel";
+import { ensureZUp } from "../lib/axisTransform";
 import { SENSOR_BY_PRESET, type SensorConfig } from "../lib/sensorConfig";
 import { emptyCloud, type PointCloud } from "../lib/types";
 
@@ -23,10 +24,14 @@ export default function Extra04Travel() {
   const [presetId, setPresetId] = useState<PresetId>("kitti");
   const sensor: SensorConfig | null = SENSOR_BY_PRESET[presetId] ?? null;
 
+  // TRAVEL inherits the Z-up assumption from its Patchwork-based ground
+  // pre-pass; normalize per-preset before passing to runTravel.
+  const zUpCloud = useMemo(() => ensureZUp(raw, presetId), [raw, presetId]);
+
   const result = useMemo(() => {
-    if (!sensor || raw.count === 0) return null;
-    return runTravel(raw, sensor);
-  }, [raw, sensor]);
+    if (!sensor || zUpCloud.count === 0) return null;
+    return runTravel(zUpCloud, sensor);
+  }, [zUpCloud, sensor]);
 
   // Persistent color matcher so cluster colors stay stable when the user
   // re-selects the same preset (avoids flicker on remount).