VoxelForge/Standalone/Research/WorldAssemblerM3/Research3/REPORT.md

# Research R3 — floor ownership on an overlapping helical passage

## Ranked recommendation and experiment

**Rank 1: resolve the floor owner only from floor-near route candidates.** For a voxel within half a 25 cm voxel of a candidate floor (`abs(candidateFloorZ - qz) <= 0.125 m`), require that candidate to be within the bore radius in XY, then choose the nearest 3D floor point; break exact ties by lower stable segment index. If no such candidate exists, keep the existing floor/player fallback. Keep the tube owner separate: this rule chooses the floor cap, not the tube SDF.

Do not use a strict `candidateFloorZ <= qz` test. At 12.5 cm sampling, a voxel can round just below its true floor; strict-below then excludes the correct segment and selects the previous segment. In the synthetic test this made a 23.8 cm peak-to-peak floor error. The half-voxel symmetric band retained the correct floor candidate.

The 0.938 m ripple period in L38 is also the expected chord spacing of a 3 m radius, 20-segment turn: `2 R sin(pi/20) = 0.9386 m`. That ties the observed period to the route control-point interval. The full audit still needs to confirm whether a local floor-owner band removes its ripple.

### Synthetic measurements

The helix used the L27 FI Style 2 main-path measurements: 3.0 m mean centerline radius, 3.31 m vertical pitch, 12.95 turns, and 20 route controls per turn. The requested 4.5 m bore radius models the enlarged mouth; the same run was repeated at the 3.0 m mid-bore radius. Queries follow the analytic floor path at 0.125 m arc-length spacing; each position is rounded to a 0.125 m grid. There are 1,984 probes. The table reports peak-to-peak and maximum absolute error of selected floor height minus analytic floor height.

| Ownership rule | 4.5 m bore p-p / max abs | 3.0 m bore p-p / max abs |
|---|---:|---:|
| Analytic closest helix centerline | 3.372 / 3.372 m | 3.329 / 3.329 m |
| Segment closest centerline | 3.387 / 3.383 m | 3.329 / 3.325 m |
| Nearest 3D floor point | 0.029 / 0.015 m | 0.029 / 0.015 m |
| Floor strictly below voxel, within bore radius | 0.238 / 0.224 m | 0.238 / 0.224 m |
| Floor within ±0.125 m and bore radius | 0.029 / 0.015 m | 0.029 / 0.015 m |
| Highest floor below voxel, within bore radius | 0.282 / 0.224 m | 0.282 / 0.224 m |
| Height-bin local segment ±1, nearest floor point | 0.029 / 0.015 m | 0.029 / 0.015 m |
| Helix angle plus height turn index | 0.030 / 0.015 m | 0.030 / 0.015 m |

The exact-curve reference searches all local minima over the finite helix and refines them with golden-section minimization; the other segment rules reproduce the carver's XY chord projection and lateral Catmull–Rom smoothing. The analytic centerline rule is wrong for floor ownership: with `bore radius > pitch/2`, a floor sample is vertically closer to the centerline on a neighboring turn. The floor-point and height-window rules agree on this ideal route. The test does **not** reproduce L38's reported 8.6 cm floor ripple; it establishes the failure modes, but the proposed guard remains a candidate until the real FI Style 2 audit is rerun.

Three additional monotone-grade style-like paths were sampled at 0.125 m: straight, a sinusoidal worm, and a scalloped cascade. Height-bin local ownership had p-p errors `0.005 / 0.030 / 0.031 m` (max absolute `0.003 / 0.016 / 0.016 m`). Nearest centerline ownership had `0.097 / 0.116 / 0.121 m` p-p. The literal strict-below-plus-radius rule had `0.203 / 0.231 / 11.567 m` p-p; the cascade's horizontal loops make a far-lower segment eligible. This disproves a one-sided “below and within radius” rule for shared use.

Reproduction: `taskset -c 0-11 prlimit --as=6442450944 -- python3 Saved/Linux/research/r3_helix_owner.py`.

## Math and code placement

For route point `C(s)` and radius `r(s)`, the carve floor is `F(s) = C_z(s) - r(s) + 0.15 m`. The planner stores `C_z = playerZ + r - 1.38 m`, so `F = playerZ - 1.23 m`. The radius cancels and the floor remains monotone wherever authored `playerZ` is monotone. The straight, worm, spiral, and cascading styles change the XY route; the planner assigns their Z profile from cumulative horizontal route distance. Confirm monotonicity on a candidate range and use the existing nearest-floor fallback for flat or non-monotone mouth/landing spans.

In `ApplyResolvedStratePassageCarves` (`Standalone/Core/src/ShapeWorldInternal.h`), add a `nearFloorCandidate` alongside `nearestFloorCandidate`. In the existing segment visitor, after computing `routeFloorQ` and horizontal distance squared, accept it into the new candidate only when `abs(routeFloorQ - qz) <= 0.125*qPerMetre` and horizontal distance squared is at most the interpolated radius squared. Select minimum floor-point distance, with stable segment-index tie-break. Apply that candidate only when valid; preserve the existing fallback otherwise. The current wide `carveBegin/carveEnd` range is around the `floorProfile`, so its monotone bounds already cover this band; alternatively, binary-search `F(s)` and visit the bracket segment plus its neighbors.

This is style-independent: the profile comes from route control points, not helix angle, generator type, or RNG. The incremental version costs a few comparisons and one squared-distance comparison for segments already visited. A narrowed search costs one binary search plus at most three segment evaluations. Neither needs `atan2`, trigonometric roots, iteration to convergence, or mutable state. Fixed-point comparisons and the stable segment tie-break preserve worker-count and peer determinism.

## Alternatives and distance-field literature

For a circular helix `gamma(t) = (R cos t, R sin t, b t)` and query `(rho cos phi, rho sin phi, z)`,

`D²(t) = rho² + R² + (b t - z)² - 2 R rho cos(t - phi)`.

Stationary points solve `u + e sin(u) = M`, with `u = t - phi`, `e = R rho / b²`, and `M = z/b - phi`. There is no elementary closed form. For the finite, radius-varying route, a safe reference solver brackets stationary candidates over turns, evaluates those roots and both endpoints, and compares distances. A recent 2026 preprint proves a principal-branch minimizer for an ideal infinite circular helix, despite multiple stationary roots, but it is not peer reviewed and does not cover our finite Catmull-smoothed route. Even a perfect Euclidean closest point is the wrong floor owner when the floor cap is offset below the centerline.

For floor probes on an ideal helix, an angle/height turn index can be written directly. With pitch `p = 2 pi b`, centerline height `z0 + b t`, and floor `z0 + b t - r + lift`, take `phi = atan2(qy-axisY, qx-axisX)` and

`n = round((qz - z0 - b phi + r - lift) / p)`, `t = phi + 2 pi n`.

Clamp or test the finite endpoints. This is cheap for a known helix and gives 0.030 m p-p error in the synthetic case, but it needs axis/pitch/radius metadata and has no direct equivalent for Straight, Worm, or Cascading. Use height only to disambiguate a local route interval in the shared path.

A hard union of independently floor-limited coils is mathematically the union of their void sets (use `min` for negative-inside SDFs; this code's positive-air density reverses that to `max`). It does not preserve a single walkable tread. The 3 m mid-bore and 3.31 m pitch satisfy `2r > pitch`, so adjacent swept tubes intersect and the union opens a route through the intervening floor/support. At the 4.5 m mouth the overlap is larger. Smooth min/max adds a fillet in the band where the fields are close; the polynomial smooth-min can shift the zero surface by up to `k/4`, which can easily exceed the 1.5 cm floor budget. Keep smooth CSG away from the hard floor cap.

CAD formulations for canal/pipe surfaces reduce distance queries to one-parameter root finding; they do not provide a cheap generic shortcut for this floor-owner query. Line-swept-sphere methods are closer to the current tube field, while high-curvature arbitrary cross-section sweeps may not have a globally smooth continuous distance field. Our control-point sweep is already a compact approximation, so changing the candidate ownership is lower cost than replacing it with a denser exact sweep representation.

References:

- [Closest Points on a Circular Helix and Kepler's Equation (2026 preprint)](https://www.preprints.org/manuscript/202608.1202) — stationary equation, multiple roots, and principal-branch result; the paper labels itself non-peer-reviewed.
- [Efficient point-projection to freeform curves and surfaces](https://doi.org/10.1016/j.cagd.2011.04.002) — geometric culling followed by numerical projection; treats monotone spiral curves specially.
- [Fast Distance Computation Between a Point and Cylinders, Cones, Line-Swept Spheres and Cone-Spheres](https://doi.org/10.1080/10867651.2004.10504892) and [Minimum distance between a canal surface and a simple surface](https://doi.org/10.1016/S0010-4485(02)00123-9) — swept-sphere and varying-radius canal-surface distance queries.
- [Iñigo Quílez, Smooth Minimum](https://archive.ph/9Z4dZ) and [distance-function modeling](https://vodacek.zvb.cz/archiv/101.html) — hard min/max operations, polynomial smooth-min formula, blend band, and distance-field caveats.
- [Synthesizing Geologically Coherent Cave Networks](https://diglib.eg.org/items/a4e7985c-af52-4b55-bd1a-eeeff6c47422) — uses compact sweep primitives for straighter conduits and sampled-sphere unions for tortuous conduits to keep a continuous 1-Lipschitz field; the latter costs more memory.
- [Feng and Crane, A Heat Method for Generalized Signed Distance](https://nzfeng.github.io/research/SignedHeatMethod/index.html) — robust generalized distance for broken/noisy/self-intersecting geometry; it solves global sparse systems, a dense offline option rather than a cheap independent per-voxel owner query.
- Local context: `Standalone/Research/WorldAssemblerM3/Linux27/REPORT.md`, `Standalone/Research/WorldAssemblerM3/Linux38/REPORT.md`, `Standalone/Core/src/ResolvedLayoutInternal.h`, and `Standalone/Core/src/ShapeWorldInternal.h`.