fix(fractal-dim): oracle-correct box-count & perimeter dimensions

[sameeul]

Summary

Corrects the accuracy of the 2D fractal-dimension features (FRACT_DIM_BOXCOUNT,
FRACT_DIM_PERIMETER) and validates them against external oracles — analytic shapes with a known
dimension, and the ImageJ/FracLac tool. Follows up the sign/aggregation fix already on main.

Before → after (the accuracy bugs, on shapes with known truth):

shape	feature	before	after	truth
filled square	box-count	1.75	2.000	2.000
Sierpinski triangle	box-count	1.39	1.585	log2(3) = 1.585
Koch snowflake	perimeter	out of range	1.266	log4/log3 = 1.262

Root cause

Box counting is grid-registration sensitive. Power2PaddedImageMatrix padded to a power of two
strictly larger than the ROI (closest_pow2) and centered it, so the ROI never lined up
with the coarse boxes — halving the box size didn't cleanly quadruple the count, biasing the
dimension low on every shape. The perimeter path additionally truncated the perimeter to int
and added a broken tail chord (variable length + squared distance instead of the Euclidean chord),
pushing FRACT_DIM_PERIMETER out of the valid [1,2] range.

Changes

Feature (fractal_dim.cpp, image_matrix.h, helpers/helpers.h)

• Box-count: tight power-of-two canvas (ceil_pow2) with the ROI at the grid origin (replaces
  closest_pow2 + centering). Auto-switch on ROI size — large ROIs use a single aligned grid (fast
  early-exit tile scan), small ROIs shift the grid over 4 origins and take the minimum count (as
  FracLac does). Perf-neutral (large-ROI ~16 ms, small ~35 µs).
• Perimeter: clean closed-contour Richardson divider — double perimeter, dropped tail chord,
  mean-ruler-length scale.
• Shared least-squares loglog_slope estimator (box -slope, perimeter 1-slope).
• ceil_pow2 rewritten branch-free / overflow-safe; the now-unused closest_pow2 removed.

Tests (tests/python/test_fractal_dim_oracle.py, tests/test_shape_morphology_2d.h, tests/data/)

• Analytic-shape oracle tests (numpy-only, run in CI): box-count square→2, line→1,
  Sierpinski→log2(3); perimeter disk→1, Koch→log4/log3.
• New committed fixture tests/data/fractal_blob512_seg.ome.tif — a large (512×512) irregular
  single ROI, the kind of object a microscopy segmentation produces — loaded from disk by both
  the C++ and Python suites and validated against offline ImageJ/FracLac oracles.

Oracle validation

Each row is a real validation, not a self-referential snapshot:

• analytic — a shape with a known closed-form dimension.
• same-method — compared to an independent implementation (ImageJ/FracLac) of the same
  algorithm. This validates Nyxus' implementation (a third-party tool agreeing is genuine
  corroboration — it is what caught the 1.75-vs-2.0 bug; a self-consistency pin never would). Same
  method ⇒ tight tolerance expected.
• cross-method — compared to a different algorithm estimating the same dimension; convergent
  validity (~10%).

shape	feature	truth	oracle (ImageJ/FracLac)	nyxus	validation
filled square	box-count	2.000	2.000	2.000	analytic + same-method ✓
straight line	box-count	1.000	1.000	1.000	analytic + same-method ✓
Sierpinski triangle	box-count	1.585	1.585	1.585	analytic + same-method ✓
disk	perimeter	1.000	—	1.02	analytic ✓
Koch snowflake	perimeter	1.262	—	1.266	analytic ✓ (err 0.004)
512² blob ROI	box-count	—	1.8706	within 1%	same-method ✓
512² blob ROI	perimeter	—	1.0493 (edge box-count)	within 10%	cross-method ✓

Why a large ROI. A fractal dimension is a scaling measurement — meaningful only across enough
scales. The 512² blob fits 9 dyadic box sizes and exercises the production single-grid (large-ROI)
path. On it the grid registration is stable: Nyxus' single grid and FracLac's origin-aligned grid
agree to ~0.5% — a genuine implementation check. (An earlier iteration validated on a 154-px ROI,
which fit only ~5 box sizes and sat in the small-ROI shifting-grid path — a weaker, borderline
fixture.) FracLac is GUI-only, so the box-count oracle (single origin-aligned grid) and the perimeter
oracle (box count of the ROI edge) were read from the FracLac GUI offline and pinned as constants.

Research note: divider vs box-counting for FRACT_DIM_PERIMETER

FRACT_DIM_PERIMETER uses the Richardson divider; the perimeter oracle is FracLac's box-count of the
ROI edge — a different algorithm. They estimate the same boundary dimension:

• They provably coincide for strictly self-similar fractals (box-counting / Minkowski,
  divider/compass, Hausdorff dimensions all equal) — which is why Nyxus' divider recovers the Koch
  snowflake to 0.004. Divergence appears only on finite, digitized, non-self-similar curves and
  shrinks with resolution (on the 512² blob, 9 box sizes, divider and box-count-of-edge agree to ~1%).
• The direction of divergence is not universal. A benchmark on the Australia coastline reports
  box-count 1.143 vs divider 1.130 (Δ≈0.013) and states "the divider dimension more accurately
  represents the irregularity of a coastline"
  (Sci. Rep. 2021).
• The divider is the theoretically preferred boundary dimension (Mandelbrot's original coastline
  method); box-counting was adopted mainly because it removes the divider's bookkeeping ambiguities
  and automates for any set — not because it is more accurate for lines. See Klinkenberg,
  A review of methods used to determine the fractal dimension of linear features
  (Math. Geology 1994).

We keep the divider (its DIN ISO 9276-6 "structured walk" heritage) because it recovers the one
analytic ground truth essentially exactly. A multi-start averaging variant (the divider analog of
shifting grids) was implemented and rejected — it degraded the Koch recovery from 1.266 to 1.37.

🤖 Generated with Claude Code

[darkclad]

Nyxus::closest_pow2 is not used anymore, can be removed

[sameeul]

Removed.

[darkclad]

Overflow issue for a > 2^30, p <<= 1 goes negative and goes into infinite loop
Suggesting either rewrite it like this
inline uint32_t ceil_pow2(uint32_t a) {
if (a == 0) return 1;
if (a > (1u << 31)) return 0; // or UINT_MAX / assert — pick a policy
uint32_t x = a - 1;
x |= x>>1; x|=x>>2; x|=x>>4; x|=x>>8; x|=x>>16;
return x + 1;
}

or switch to uint64_t

#include
inline uint64_t ceil_pow2(uint32_t a) {
return a <= 1 ? 1 : std::bit_ceil<uint64_t>(a);
}

[darkclad]

Magic number, need a comment on why we look for 32

[sameeul]

comments added.

[darkclad]

Nit (non-blocking): flag that 1.3891 is a same-method pin, not external ground truth.
This value comes from the ImageJ/FracLac shifting-grid box count — the same algorithm Nyxus runs — so the 1% assertion below is really a regression/self-consistency pin, not an independent oracle. That's fine and the header comment (L72) already says "SAME method as Nyxus", but since it sits in a map literally named ...oracle... next to the genuinely cross-method FRACT_DIM_PERIMETER, it's easy to misread 1.3891 as external corroboration. Suggest a one-line inline marker so the distinction survives a skim, e.g.:

{"FRACT_DIM_BOXCOUNT", 1.3891}, // self-consistency pin: SAME shifting-grid method as Nyxus (not independent validation)
{"FRACT_DIM_PERIMETER", 1.163}, // cross-method (edge box-count vs divider) — the real external check
The independent validation here is the analytic shapes (square→2, line→1, Sierpinski→log₂3, …) and the cross-method perimeter; the 154-px box-count is a pin.

[sameeul]

Updated the test with a new image of arbitrary ROI, typically found in microscopy images. The numbers have been vetted by running ImageJ/FracLac locally.

[darkclad]

Nit (non-blocking): same as the C++ side — mark this as a same-method pin.
ORACLE_BOXCOUNT_154 = 1.389 is the offline ImageJ shifting-grid box count, i.e. the same method Nyxus uses, so abs(bc - 1.389) < 0.02 is a self-consistency check rather than independent corroboration (the trailing comment "<0.001" makes that clear — a near-exact match is expected precisely because it's the same algorithm). Consider renaming to make intent obvious at the call site, or at minimum keep the comment explicit:

ORACLE_BOXCOUNT_154 = 1.389 # SAME-method pin (ImageJ shifting-grid == nyxus); not independent
ORACLE_PERIMETER_154_EDGE = 1.163 # cross-method (edge box-count vs divider) — independent check
No change to the assertion itself needed; the tight 0.02 tolerance is correct for a same-method pin. The genuinely independent Python checks remain the analytic-shape tests and the cross-method perimeter.

[sameeul]

Updated the test with a new image of arbitrary ROI, typically found in microscopy images. The numbers have been vetted by running ImageJ/FracLac locally.

[darkclad]

It is worth checking that K is truly single countour
// The divider assumes ONE closed contour. Multi-contour ROIs (holes / disconnected
// fragments) concatenate into K and inject spurious seam chords that bias the dimension.
assert(r.contour_count() <= 1 && "perimeter fdim assumes single contour");

[darkclad]

Nit (non-blocking, maintenance watch-point): this harness hand-copies the production ROI-preprocessing path.
load_test_roi_data only fills raw_pixels, so L339–342 re-implement inline what the real masked loader does — make_nonanisotropic_aabb() → aux_image_matrix.allocate(...) → calculate_from_pixelcloud(...) → initialize_fvals() (plus the hardcoded label 102). That's correct for the current loader and the oracle values are meaningful, but nothing keeps it in sync: if production ever changes how an ROI is finalized (AABB/anisotropy convention, matrix fill, a new normalization step), this fixture keeps building the ROI the old way and would still pass — validating fractal dimensions against an ROI the real pipeline would never produce.
Two ways to de-risk, in order of preference:

route the test through the same finalize entry point the loader uses instead of duplicating its steps, so a production change flows in automatically; or
if no shared entry point exists, add a // KEEP IN SYNC WITH marker next to the make_nonanisotropic_aabb block and an assert pinning the resulting AABB/matrix dims, so drift is visible. Not a blocker for this PR (the reconstruction is already commented and matches production today) — just flagging the hidden coupling so whoever touches ROI preprocessing later updates it here too.