linumpy.mosaic.interpolation#

Slice interpolation utilities for missing serial sections.

Single strategy: interpolate_z_morph() – z-aware morphing via fractional affine warps (T**alpha, scipy.linalg.fractional_matrix_power()). Reconstructs a synthetic slice that transitions along Z from vol_before[-1] to vol_after[0], matching the physical geometry of serial sectioning.

When any quality gate fails, interpolate_z_morph() does not fabricate a volume. It returns (None, diagnostics) with diagnostics["interpolation_failed"] = True and a specific fallback_reason. The caller must honour this by not emitting a reconstructed slice – a blend of the two neighbours would also be fabricated data, with the added failure mode of ghost/double-contour artefacts whenever the two neighbours differ.

Downstream of a failed interpolation, the pipeline treats the slice as a genuine multi-slice gap: no zarr is produced, the manifest fragment records interpolation_failed=true, and slice_config_final.csv surfaces the failure so the final report can flag it.

Returns (volume, diagnostics) where volume is None on failure and diagnostics is always a JSON-serialisable dict.

See docs/SLICE_INTERPOLATION_FEATURE.md for the scientific rationale, failure modes, and the connection to slice_config.csv (interpolated, interpolation_failed, interpolation_fallback_reason columns).

Attributes#

logger

Functions#

interpolate_average(vol_before, vol_after)

Return a 50/50 average of two adjacent volumes.

interpolate_weighted(vol_before, vol_after[, sigma])

Weighted average with Gaussian smoothing along Z.

find_best_overlap_planes(vol_before, vol_after[, ...])

Find the best-correlated plane pair at the volume boundary.

interpolate_z_morph(vol_before, vol_after[, output_z, ...])

Z-aware morphing interpolation.

Module Contents#

linumpy.mosaic.interpolation.logger[source]#
linumpy.mosaic.interpolation.interpolate_average(vol_before, vol_after)[source]#

Return a 50/50 average of two adjacent volumes.

Parameters:
Return type:

numpy.ndarray

linumpy.mosaic.interpolation.interpolate_weighted(vol_before, vol_after, sigma=2.0)[source]#

Weighted average with Gaussian smoothing along Z.

Parameters:
Return type:

numpy.ndarray

linumpy.mosaic.interpolation.find_best_overlap_planes(vol_before, vol_after, search_window=5, min_foreground_fraction=0.1)[source]#

Find the best-correlated plane pair at the volume boundary.

In serial sectioning the physically adjacent tissue is near the bottom of vol_before and the top of vol_after. This function searches the last search_window planes of vol_before against the first search_window planes of vol_after using normalised cross-correlation on the central ROI, skipping planes whose foreground fraction is below min_foreground_fraction.

Returns (ref_before, ref_after, best_corr). When no candidate pair passes the foreground filter, the corner planes are returned with a correlation of -inf.

Parameters:
Return type:

tuple[int, int, float]

linumpy.mosaic.interpolation.interpolate_z_morph(vol_before, vol_after, output_z=None, metric='MSE', max_iterations=1000, overlap_search_window=5, min_overlap_correlation=0.3, reference_slab_size=3, min_foreground_fraction=0.1, min_ncc_improvement=0.05, blend_method='gaussian')[source]#

Z-aware morphing interpolation.

Registers vol_after[0] to vol_before[-1] to get an affine T, then for each output plane at fractional depth alpha ∈ [0, 1] warps the before-boundary by T**alpha and the after-boundary by T**(alpha - 1), cross-fading with weight alpha. Output top/bottom planes match the boundary planes exactly.

Hard skip on gate failure. When any quality gate fails (no_foreground_planes, low_overlap_ncc, registration_exception, reg_did_not_improve, affine_determinant_non_positive) the function returns (None, diagnostics) with diagnostics["interpolation_failed"] = True and a specific fallback_reason. No fabricated volume is produced – blending the two neighbours would also be made-up data, with the added failure mode of ghost/double-contour artefacts whenever the two neighbours differ.

See docs/SLICE_INTERPOLATION_FEATURE.md for the physical model, the rationale for the hard-skip behaviour, and parameter-tuning guidance.

Returns:

  • volume (np.ndarray | None) – Interpolated 3D volume, shape (output_z or min(nz_before, nz_after), H, W), or None when a quality gate fails.

  • diagnostics (dict) – JSON-serialisable trace of the attempt.

Parameters:
Return type:

tuple[numpy.ndarray | None, dict[str, Any]]