BUG: Correct X/Y surface-area weights for unequal voxel spacing #1773

Recommended to fix this with issue #1780

Problem and scope

Compute Surface Area to Volume & Sphericity uses the wrong face areas for X and Y neighbors. The defect affects both the in-memory Direct algorithm and the OOC Scanline algorithm. Move this correction to a separate branch so its in-memory fix can merge independently of the OOC audit work.

The surface-area/volume error was reproduced in Windows tests on 2026-10-09 in all three supported scenarios: Direct with resident arrays, Scanline with resident arrays, and Scanline with actual HDF5 arrays. No Linux/macOS runtime result is claimed here.

Cause

Pinned sources at the published PR #1764 head, 9a28a90f0f7a5d42fb5f17f36c84597b640fcac9:

• Direct neighbor directions and contributions.
• Scanline areas and neighbor contributions.

For spacing (dx,dy,dz), a face perpendicular to X has area dy*dz, and a face perpendicular to Y has area dx*dz. Both implementations apply these two weights to the opposite directions. Z faces correctly use dx*dy.

The error is masked when X/Y spacing is equal, or when the shape's X/Y boundary contributions cancel the swap. Agreement between the two algorithms does not detect their shared error.

Reproduction with an independent physical oracle

Use a 5 x 5 x 5 image, origin (0,0,0), spacing (2,3,5), and scalar int32 FeatureIds. Fill all 125 cells with feature 1, then put feature 2 in two interior adjacent cells. Set NumCells to {0,123,2}. This positive enclosing feature isolates the face-area issue from image-exterior and feature-zero policies. Disable optional sphericity for this initial ratio diagnostic.

With X-fastest indexing, the first feature-2 cell is index 62, coordinates (2,2,2). Use separate fresh fixtures for second index 63 (X), 67 (Y), and 87 (Z).

For a physical box of dimensions (a,b,c), calculate expected area as 2*(a*b+a*c+b*c) and volume as a*b*c.

A fourth control uses unit spacing and the X pair; expected and observed ratio are both 5.

The diagnostics checked input values, physical centers/indexing, shapes, actual backing stores and algorithm selection. Preflight and execution returned valid results. Only the X/Y ratio checks failed: four failures across the two resident scenarios, then the same two failures on actual HDF5 storage. Z and unit-spacing controls passed. Temporary diagnostic overlays were removed; incorrect results were not accepted as expected values.

Correction and impact

Apply the correct directional weights in both algorithms and add regressions using physical dimensions, not one algorithm's output as the other's reference. Preserve validation guards, cancellation, bounded slice I/O and the existing treatment of feature zero and image-exterior faces.

This intentionally changes incorrect results for affected existing in-memory and OOC pipelines. Unit-spacing results should remain unchanged. Optional sphericity uses the same area as its denominator (Direct, Scanline), so its affected values should also change; that follows from the source, but anisotropic sphericity was not measured in the recorded diagnostic.

Update relevant documentation/release notes. Review affected reference data against an independent physical oracle; do not regenerate references solely to make tests pass. The separate zero-neighbor/documentation question is outside this correction.

Acceptance checks

• X, Y and Z interior-pair fixtures match the analytical area/volume values in both algorithms and on actual HDF5 stores.
• Include unequal X/Y spacing and shapes with unequal X/Y boundary contributions; retain unit-spacing and Z controls.
• Test sphericity enabled and disabled with independently calculated expected values.
• Preserve all input values, shapes, valid stores, cancellation and I/O error behavior.
• Keep existing archive controls and validate any changed nonuniform-spacing references independently.
• Run supported native configurations. Record the distinction between source evidence and runtime passes.

No production correction is included in the current OOC audit branch. This issue records the shared defect for separate implementation; it does not assert when the defect was first introduced.