feat: slice interpolation for missing sections (z-morph)

[FIrgolitsch]

Stacked PR 8/22 — review order: #115 → #97 → #98 → #99 → #100 → #101 → #108 → #106 → #107 → #87 → #116 → #110 → #111 → #40 → #112 → #113 → #117 → #118 → #120 → #121 → #122 → #123 → #124 → #125

Base: pr-l-manual-align. Retargets to main as upstream PRs merge.

---

Summary

Reconstruct a single missing serial section from its two neighbours using z-aware affine morphing (zmorph). An affine transform T between the two boundary planes is computed, then every output plane at fractional depth alpha is produced by warping the before-boundary by T**alpha and the after-boundary by T**(alpha-1) and cross-fading the two (scipy.linalg.fractional_matrix_power + SimpleITK). This matches the physical geometry of serial sectioning instead of producing a blurry mean.

Key design points

• Single strategy. interpolate_z_morph is the default. interpolate_average / interpolate_weighted are retained only as explicit, user-requested baselines via --method.
• Hard skip on gate failure. When boundary registration or NCC-improvement gates fail, the function returns (None, diagnostics) with a specific fallback_reason. The CLI then emits no zarr — the slot is left as a genuine gap rather than fabricated data. A manifest fragment and diagnostics JSON are still written so the failure surfaces in slice_config_final.csv and the final report.
• Only single-slice gaps. Two or more consecutive missing slices carry insufficient information and are explicitly rejected.
• NCC-based boundary selection via find_best_overlap_planes scans a window of candidate planes on each side and picks the pair with the best normalised cross-correlation before registration.
• Pipeline integration. Produces per-slice JSON + manifest fragments; --finalise mode aggregates all fragments and updates slice_config.csv → slice_config_final.csv with interpolated, interpolation_failed, interpolation_fallback_reason columns for use by the Nextflow pipeline (feat: updated Nextflow workflows with profiles, auto-assess, rehoming #108).

Files (4)

• linumpy/stitching/interpolation.py — interpolate_z_morph, interpolate_average, interpolate_weighted, find_best_overlap_planes, NCC / foreground-fraction quality gates, Gaussian-feather blending, fractional-affine helpers
• scripts/linum_interpolate_missing_slice.py — CLI. Modes:
  • default: slice_before slice_after output — emit interpolated ome.zarr + diagnostics
  • --preview — render an XY/XZ preview PNG instead of writing a zarr
  • --finalise --slice_config_in --slice_config_out --fragments — merge per-slice fragments back into slice_config.csv
  • Tuning flags: --method {zmorph,average,weighted}, --blend_method {linear,gaussian}, --registration_metric {MSE,CC,MI}, --overlap_search_window, --min_overlap_correlation, --reference_slab_size, --min_foreground_fraction, --min_ncc_improvement
• linumpy/tests/test_stitching_interpolation.py
• scripts/tests/test_interpolate_missing_slice.py

See docs/SLICE_INTERPOLATION_FEATURE.md for the physical model and parameter tuning.

[CHrlS98]

I have a few questions on how it works. see comments below. Also a few changes requested.

[CHrlS98]

Two additional comments on your latest changes. Some comments from previous review are not resolved yet. Take your time, I just want to make sure I'm not too much of a bottleneck.