Patchwork+TRAVEL: tighten VLP-16 ground gate, sensor-specific TRAVEL thresholds

Patchwork fix — match upstream determine_ground_likelihood_estimation_status:
  - elevation gate now indexes by *global* ring (not by zone), so
    elevation_thresholds[0..3] map to the inner four rings as in
    patchwork.hpp:818-827.
  - FLAT_ENOUGH override added: high but very flat patches (flatness <
    flat_thr) still count as ground (ramps, curbs).
  - Outer rings now apply the global-elevation veto when
    useGlobalElevation is on. This is what rejects ceilings on VLP-16
    indoor (z_centroid > 0 in sensor frame).
  - FEW_POINTS branch (idxs ≤ num_min_pts) now marks all bin points as
    ground, matching the upstream denoising heuristic.

CzmConfig grew useGlobalElevation + globalElevationThr (true/0.0 for
VLP-16, false/-0.5 for HDL-64).

TRAVEL clustering — separate horz/vert merge thresholds (0.4/0.5 for
HDL-64 from kitti_params.yaml; tighter 0.3/0.4 for VLP-16 indoor).
Defaults read from sensor.rangeImage so each chapter pulls
sensor-appropriate values.

Smoke test (scripts/smoke-patchwork.mjs) confirms the fix:
  VLP-16 indoor: floor 96.2% ground, ceiling 0%, walls 0%
  HDL-64 outdoor: ground 97.7%, cars 0%

Author: LimHyungTae

web/scripts/smoke-patchwork.mjs

@@ -0,0 +1,147 @@
+// Smoke test: synthetic indoor scene → Patchwork should classify floor as
+// ground and reject ceiling/walls. Run with:
+//   npx tsx scripts/smoke-patchwork.mjs
+
+const { runPatchwork } = await import("../src/lib/filters/patchwork.ts");
+const { SENSOR_VLP16, SENSOR_HDL64 } = await import("../src/lib/sensorConfig.ts");
+const { cloudFromPositions } = await import("../src/lib/types.ts");
+
+function makeIndoorScene() {
+  // VLP-16 sensor at origin, mounted 0.6 m above floor (so floor z = -0.6).
+  // 8 m × 8 m × 3 m room, ceiling at z = +2.4. Add some object boxes.
+  const pts = [];
+  const rand = mulberry32(42);
+  // Floor: scatter 3000 points across the room.
+  for (let i = 0; i < 3000; i++) {
+    pts.push((rand() - 0.5) * 6, (rand() - 0.5) * 6, -0.6 + (rand() - 0.5) * 0.02);
+  }
+  // Ceiling: 1500 points.
+  for (let i = 0; i < 1500; i++) {
+    pts.push((rand() - 0.5) * 6, (rand() - 0.5) * 6, 2.4 + (rand() - 0.5) * 0.02);
+  }
+  // 4 walls, 800 points each.
+  for (let w = 0; w < 4; w++) {
+    for (let i = 0; i < 800; i++) {
+      const along = (rand() - 0.5) * 6;
+      const up = -0.6 + rand() * 3;
+      const wallX = w === 0 ? 3 : w === 1 ? -3 : along;
+      const wallY = w === 0 ? along : w === 1 ? along : w === 2 ? 3 : -3;
+      pts.push(wallX, wallY, up);
+    }
+  }
+  // 3 box-shaped obstacles on the floor.
+  const objs = [
+    [1.2, 0.5, 0.4],
+    [-1.5, 1.8, 0.6],
+    [0.5, -1.6, 0.5],
+  ];
+  for (const [cx, cy, height] of objs) {
+    for (let i = 0; i < 600; i++) {
+      pts.push(cx + (rand() - 0.5) * 0.6, cy + (rand() - 0.5) * 0.6, -0.6 + rand() * height);
+    }
+  }
+  return cloudFromPositions(new Float32Array(pts));
+}
+
+function makeOutdoorKittiLike() {
+  // HDL-64 sensor at origin, mounted 1.723 m above ground (so ground z ≈ -1.7).
+  // Flat ground out to 80 m, plus a few "vehicle" boxes.
+  const pts = [];
+  const rand = mulberry32(7);
+  for (let i = 0; i < 8000; i++) {
+    const r = 2 + rand() * 70;
+    const a = rand() * 2 * Math.PI;
+    pts.push(r * Math.cos(a), r * Math.sin(a), -1.723 + (rand() - 0.5) * 0.05);
+  }
+  const cars = [
+    [10, 0, 1.5, 4, 1.6],
+    [-15, 5, 1.5, 4, 1.7],
+    [3, -8, 1.6, 4, 1.7],
+  ];
+  for (const [cx, cy, w, l, h] of cars) {
+    for (let i = 0; i < 600; i++) {
+      pts.push(
+        cx + (rand() - 0.5) * w,
+        cy + (rand() - 0.5) * l,
+        -1.723 + rand() * h,
+      );
+    }
+  }
+  return cloudFromPositions(new Float32Array(pts));
+}
+
+function mulberry32(seed) {
+  let a = seed;
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function classify(cloud, isGround, zMin, zMax) {
+  let groundIn = 0,
+    nonGroundIn = 0,
+    total = 0;
+  for (let i = 0; i < cloud.count; i++) {
+    const z = cloud.positions[3 * i + 2];
+    if (z < zMin || z > zMax) continue;
+    total++;
+    if (isGround[i]) groundIn++;
+    else nonGroundIn++;
+  }
+  return { groundIn, nonGroundIn, total };
+}
+
+console.log("=== VLP-16 indoor synthetic ===");
+const indoor = makeIndoorScene();
+const ind = runPatchwork(indoor, SENSOR_VLP16);
+const floorBand = classify(indoor, ind.isGround, -0.7, -0.5);
+const ceilingBand = classify(indoor, ind.isGround, 2.3, 2.5);
+const wallBand = classify(indoor, ind.isGround, 0.0, 1.5);
+console.log(
+  `  floor   z∈[-0.7, -0.5]: ground=${floorBand.groundIn}/${floorBand.total} (${pct(floorBand)})`,
+);
+console.log(
+  `  ceiling z∈[ 2.3,  2.5]: ground=${ceilingBand.groundIn}/${ceilingBand.total} (${pct(ceilingBand)})`,
+);
+console.log(
+  `  walls   z∈[ 0.0,  1.5]: ground=${wallBand.groundIn}/${wallBand.total} (${pct(wallBand)})`,
+);
+console.log(
+  `  TOTAL: ${ind.groundCloud.count}/${indoor.count} marked ground; ${ind.uniqueRegions.length} regions`,
+);
+
+console.log("");
+console.log("=== HDL-64 outdoor synthetic ===");
+const outdoor = makeOutdoorKittiLike();
+const out = runPatchwork(outdoor, SENSOR_HDL64);
+const groundBand = classify(outdoor, out.isGround, -1.8, -1.65);
+const carBand = classify(outdoor, out.isGround, -0.8, 0.3);
+console.log(
+  `  ground z∈[-1.80, -1.65]: ground=${groundBand.groundIn}/${groundBand.total} (${pct(groundBand)})`,
+);
+console.log(
+  `  car    z∈[-0.80,  0.30]: ground=${carBand.groundIn}/${carBand.total} (${pct(carBand)})`,
+);
+console.log(
+  `  TOTAL: ${out.groundCloud.count}/${outdoor.count} marked ground; ${out.uniqueRegions.length} regions`,
+);
+
+console.log("");
+const indoorOk = floorBand.groundIn / floorBand.total > 0.7
+  && ceilingBand.groundIn / Math.max(1, ceilingBand.total) < 0.2
+  && wallBand.groundIn / Math.max(1, wallBand.total) < 0.2;
+const outdoorOk = groundBand.groundIn / groundBand.total > 0.7
+  && carBand.groundIn / Math.max(1, carBand.total) < 0.2;
+console.log(`indoor OK: ${indoorOk}`);
+console.log(`outdoor OK: ${outdoorOk}`);
+process.exit(indoorOk && outdoorOk ? 0 : 1);
+
+function pct(b) {
+  if (b.total === 0) return "—";
+  return `${((100 * b.groundIn) / b.total).toFixed(1)}%`;
+}

web/src/lib/filters/patchwork.ts

@@ -127,10 +127,33 @@ export function runPatchwork(
     arr.push(i);
   }
 
+  // Pre-compute global ring index per (zone, ring) — used for indexing into
+  // elevation_thresholds / flatness_thresholds (whose length is the number
+  // of "rings of interest", not the total ring count).
+  const ringOffsetByZone: number[] = [];
+  {
+    let acc = 0;
+    for (let z = 0; z < c.numRingsPerZone.length; z++) {
+      ringOffsetByZone.push(acc);
+      acc += c.numRingsPerZone[z];
+    }
+  }
+  const numRingsOfInterest = c.elevationThresholds.length;
+
   // R-GPF per bin.
   for (const [, idxs] of bins) {
-    if (idxs.length < c.numMinPts) continue;
     const sampleZone = pointZone[idxs[0]];
+    const sampleRing = pointRing[idxs[0]];
+
+    // FEW_POINTS branch (line 601-610 of upstream patchwork.hpp): when a bin
+    // has too few points, the original treats the entire bin as ground. The
+    // rationale (per the upstream comment): these sparse points are usually
+    // noise, and dumping them into ground keeps them out of downstream
+    // clustering / object detection.
+    if (idxs.length <= c.numMinPts) {
+      for (const i of idxs) isGround[i] = 1;
+      continue;
+    }
 
     // Sort by z ascending to find lowest-point representatives.
     const sorted = idxs.slice().sort(
@@ -214,14 +237,37 @@ export function runPatchwork(
     if (curSeeds.length < 3) continue;
 
     const upright = Math.abs(normal[2]) > c.uprightnessThr;
-    const elevThr = c.elevationThresholds[Math.min(sampleZone, c.elevationThresholds.length - 1)];
-    const flatThr = c.flatnessThresholds[Math.min(sampleZone, c.flatnessThresholds.length - 1)];
-    // Patchwork applies the elevation gate strictly only on the outer two zones.
-    const elevOk = sampleZone < 2 || centroidZ < -c.sensorHeight + elevThr;
+    if (!upright) continue; // TOO_TILTED — reject
+
     const flatness = smallestEig / sumEig;
-    const flatOk = flatness < flatThr;
+    const globalRing = ringOffsetByZone[sampleZone] + sampleRing;
+
+    // Mirror upstream determine_ground_likelihood_estimation_status:
+    //   inner rings (globalRing < numRingsOfInterest):
+    //     elevation > -h + elev_thr[ring]?
+    //       no  → UPRIGHT_ENOUGH (ground)
+    //       yes → flatness < flat_thr[ring]?
+    //               yes → FLAT_ENOUGH (ground — flat patches at unusual
+    //                     elevation are kept; e.g. ramps, curbs)
+    //               no  → TOO_HIGH_ELEVATION (reject, e.g. car roofs)
+    //   outer rings:
+    //     useGlobalElevation && z_centroid > global_thr → reject
+    //     else → UPRIGHT_ENOUGH (ground)
+    let acceptAsGround: boolean;
+    if (globalRing < numRingsOfInterest) {
+      const elevThr = c.elevationThresholds[globalRing];
+      const flatThr = c.flatnessThresholds[globalRing];
+      const tooHigh = centroidZ > -c.sensorHeight + elevThr;
+      if (!tooHigh) {
+        acceptAsGround = true;
+      } else {
+        acceptAsGround = flatness < flatThr;
+      }
+    } else {
+      acceptAsGround = !(c.useGlobalElevation && centroidZ > c.globalElevationThr);
+    }
 
-    if (!(upright && elevOk && flatOk)) continue;
+    if (!acceptAsGround) continue;
 
     for (const i of curSeeds) isGround[i] = 1;
   }

web/src/lib/filters/travel.ts

@@ -45,22 +45,30 @@ export type TravelResult = {
 };
 
 export type TravelOptions = {
-  /** Discontinuity threshold in meters between adjacent range pixels. */
-  depthDiffThresh: number;
+  /** Discontinuity threshold in meters between horizontally-adjacent range
+   *  pixels (azimuth direction). */
+  horzMerge: number;
+  /** Discontinuity threshold in meters between vertically-adjacent range
+   *  pixels (elevation direction). */
+  vertMerge: number;
   /** Minimum pixels for a cluster to be kept. */
   minClusterSize: number;
 };
 
-export const DEFAULT_TRAVEL_OPTS: TravelOptions = {
-  depthDiffThresh: 0.5,
-  minClusterSize: 10,
-};
+export function defaultTravelOptions(sensor: SensorConfig): TravelOptions {
+  return {
+    horzMerge: sensor.rangeImage.travelHorzMerge,
+    vertMerge: sensor.rangeImage.travelVertMerge,
+    minClusterSize: sensor.rangeImage.travelMinClusterSize,
+  };
+}
 
 export function runTravel(
   input: PointCloud,
   sensor: SensorConfig,
-  opts: TravelOptions = DEFAULT_TRAVEL_OPTS,
+  opts?: TravelOptions,
 ): TravelResult {
+  const o = opts ?? defaultTravelOptions(sensor);
   const ri = sensor.rangeImage;
   const rows = ri.rows;
   const cols = ri.cols;
@@ -144,18 +152,24 @@ export function runTravel(
       const curD = depths[cur];
 
       // 4-connected neighbors. Wrap horizontally — azimuth is periodic.
-      const neighbors = [
-        r > 0 ? (r - 1) * cols + c : -1,
-        r < rows - 1 ? (r + 1) * cols + c : -1,
-        r * cols + (c === 0 ? cols - 1 : c - 1),
-        r * cols + (c === cols - 1 ? 0 : c + 1),
-      ];
-      for (const np of neighbors) {
-        if (np < 0) continue;
+      // Vertical (row ±1) uses vertMerge; horizontal (col ±1) uses horzMerge.
+      const neighbors: { idx: number; thresh: number }[] = [];
+      if (r > 0) neighbors.push({ idx: (r - 1) * cols + c, thresh: o.vertMerge });
+      if (r < rows - 1) neighbors.push({ idx: (r + 1) * cols + c, thresh: o.vertMerge });
+      neighbors.push({
+        idx: r * cols + (c === 0 ? cols - 1 : c - 1),
+        thresh: o.horzMerge,
+      });
+      neighbors.push({
+        idx: r * cols + (c === cols - 1 ? 0 : c + 1),
+        thresh: o.horzMerge,
+      });
+
+      for (const { idx: np, thresh } of neighbors) {
         if (imagePointIdx[np] === -1) continue;
         if (imageClusterIds[np] !== 0) continue;
         const nd = depths[np];
-        if (Math.abs(nd - curD) > opts.depthDiffThresh) continue;
+        if (Math.abs(nd - curD) > thresh) continue;
         imageClusterIds[np] = id;
         queue[tail++] = np;
         members.push(np);
@@ -169,7 +183,7 @@ export function runTravel(
   const idRemap = new Int32Array(nextClusterId + 1); // 1-based
   for (let id = 1; id <= nextClusterId; id++) {
     const pixels = clusterPixels[id - 1];
-    if (pixels.length >= opts.minClusterSize) {
+    if (pixels.length >= o.minClusterSize) {
       survivors.push(pixels);
       idRemap[id] = survivors.length;
     } else {

web/src/lib/sensorConfig.ts

@@ -21,10 +21,19 @@ export type CzmConfig = {
   numRingsPerZone: number[];
   /** Length numZones — number of angular sectors within each zone. */
   numSectorsPerZone: number[];
-  /** Per-zone elevation thresholds (m, w.r.t. ground frame). */
+  /** Per-ring elevation thresholds (length = "rings of interest", typically 4).
+   *  Indexed by *global* ring index across all zones. Bins with global ring
+   *  beyond this length fall back to the global elevation gate. */
   elevationThresholds: number[];
-  /** Per-zone flatness thresholds (eigenvalue ratio). */
+  /** Per-ring flatness thresholds (eigenvalue ratio). Same indexing as
+   *  elevationThresholds. */
   flatnessThresholds: number[];
+  /** Whether outer rings use the global-elevation veto. Enable for indoor
+   *  sensors (VLP-16) where ceilings would otherwise pass as ground. */
+  useGlobalElevation: boolean;
+  /** Global elevation threshold (sensor frame). Plane centroid Z above this
+   *  is rejected as ground when useGlobalElevation = true. */
+  globalElevationThr: number;
   /** Sensor mount height above ground (positive). */
   sensorHeight: number;
   /** R-GPF: lowest-point-representative count (seed initialization). */
@@ -48,6 +57,14 @@ export type RangeImageConfig = {
   maxRange: number;
   /** Vertical FOV bounds in degrees (lower, upper). */
   vertFovDeg: [number, number];
+  /** TRAVEL AOS: depth-difference threshold (m) for horizontally-adjacent
+   *  range-image pixels to join the same cluster. */
+  travelHorzMerge: number;
+  /** TRAVEL AOS: depth-difference threshold (m) for vertically-adjacent
+   *  range-image pixels to join the same cluster. */
+  travelVertMerge: number;
+  /** TRAVEL AOS: minimum cluster size (pixels). */
+  travelMinClusterSize: number;
 };
 
 export type SensorConfig = {
@@ -69,6 +86,8 @@ export const SENSOR_VLP16: SensorConfig = {
     numSectorsPerZone: [16, 32, 56, 32],
     elevationThresholds: [0.523, 0.746, 0.879, 1.125],
     flatnessThresholds: [0.0005, 0.000725, 0.001, 0.001],
+    useGlobalElevation: true,
+    globalElevationThr: 0.0,
     sensorHeight: 0.6,
     numLpr: 20,
     numIter: 3,
@@ -83,6 +102,10 @@ export const SENSOR_VLP16: SensorConfig = {
     minRange: 0.6,
     maxRange: 60.0,
     vertFovDeg: [-15.0, 15.0],
+    // Indoor scenes have tighter depth structure than outdoor.
+    travelHorzMerge: 0.3,
+    travelVertMerge: 0.4,
+    travelMinClusterSize: 10,
   },
 };
 
@@ -98,6 +121,8 @@ export const SENSOR_HDL64: SensorConfig = {
     numSectorsPerZone: [16, 32, 56, 32],
     elevationThresholds: [0.523, 0.746, 0.879, 1.125],
     flatnessThresholds: [0.0005, 0.000725, 0.001, 0.001],
+    useGlobalElevation: false,
+    globalElevationThr: -0.5,
     sensorHeight: 1.723,
     numLpr: 20,
     numIter: 3,
@@ -112,6 +137,10 @@ export const SENSOR_HDL64: SensorConfig = {
     minRange: 1.0,
     maxRange: 80.0,
     vertFovDeg: [-24.8, 2.0],
+    // From kitti_params.yaml in the upstream TRAVEL repo.
+    travelHorzMerge: 0.4,
+    travelVertMerge: 0.5,
+    travelMinClusterSize: 10,
   },
 };