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) — stationary equation, multiple roots, and principal-branch result; the paper labels itself non-peer-reviewed.
• Efficient point-projection to freeform curves and surfaces — 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 and Minimum distance between a canal surface and a simple surface — swept-sphere and varying-radius canal-surface distance queries.
• Iñigo Quílez, Smooth Minimum and distance-function modeling — hard min/max operations, polynomial smooth-min formula, blend band, and distance-field caveats.
• Synthesizing Geologically Coherent Cave Networks — 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 — 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.