Alignment Module

alignment.py

Image registration for pre/post-stain microscopy image pairs.

The multiscale registration pipeline:

  1. Coarse boundary correlation (translation + rotation + isotropic scale)

  2. ICP affine refinement of boundary contour correspondences

  3. Optional fine homography ECC pass (disabled by default)

All functions assume images are 2D float32 arrays.

exo2micro.alignment.boundary_correlation_coarse(post_full, pre_full, coarse_scale, boundary_width, boundary_smooth, rotation_search=True, angle_range=20, angle_step=1, scale_search=True, scale_min=0.85, scale_max=1.15, scale_step=0.05)[source]

Find coarse rigid alignment by maximising boundary ring overlap.

Uses phase correlation and brute-force rotation/scale search over extracted tissue boundary rings.

Parameters:

  • post_full (ndarray) – Full-resolution post-stain image (float32).

  • pre_full (ndarray) – Full-resolution pre-stain image (float32).

  • coarse_scale (float) – Downsample factor for boundary extraction.

  • boundary_width (int) – Boundary ring thickness in pixels at coarse resolution.

  • boundary_smooth (float) – Gaussian softening sigma on the boundary ring.

  • rotation_search (bool) – Search over rotations (default True).

  • angle_range (float) – Rotation search range ±degrees (default 20).

  • angle_step (float) – Rotation search step in degrees (default 1).

  • scale_search (bool) – Search over isotropic scale factors (default True).

  • scale_min (float) – Scale search range and step.

  • scale_max (float) – Scale search range and step.

  • scale_step (float) – Scale search range and step.

Returns:

  • warp_coarse_full (ndarray) – 3x3 similarity homography at full resolution.

  • best_angle (float) – Best rotation angle found (degrees).

  • best_dx, best_dy (float) – Best translation in coarse-scale pixels.

  • post_boundary_raw, pre_boundary_raw (ndarray) – Boundary rings at coarse scale (for diagnostics).

exo2micro.alignment.prealign_phase_correlation(post_im, pre_im)[source]

Compute a coarse translational pre-alignment using phase correlation.

Parameters:

  • post_im (ndarray) – Post-stain (fixed) image (2D).

  • pre_im (ndarray) – Pre-stain image to be shifted (2D).

Returns:

  • post_full (ndarray (float32))

  • pre_shift (ndarray (float32)) – Pre-stain image shifted to coarsely align.

  • shift (tuple) – (dx, dy) shift applied.

exo2micro.alignment.refine_icp(post_full, warp_coarse, post_bnd_pts=None, pre_bnd_pts=None, bnd_scale=None, max_translation=200, max_rotation=5.0, max_scale_delta=0.1, max_scale_diff=0.05, close_threshold_px=30, close_threshold_floor=5, max_icp_iter=20)[source]

Refine coarse alignment using ICP on tissue boundary points.

Only well-matched boundary points (those already close after the coarse pass) are used, avoiding regions where tissue shapes genuinely differ.

Parameters:

  • post_full (ndarray) – Full-resolution post-stain image (float32).

  • warp_coarse (ndarray) – 3x3 coarse homography at full resolution.

  • post_bnd_pts (ndarray or None) – Nx2 boundary points for post-stain in coarse-scale coords.

  • pre_bnd_pts (ndarray or None) – Nx2 boundary points for pre-stain in post-coarse frame.

  • bnd_scale (float or None) – Conversion factor from boundary-point coords to full-res pixels.

  • max_translation (float) – Maximum allowed translation correction (default 200 px).

  • max_rotation (float) – Maximum allowed rotation correction (default 5 degrees).

  • max_scale_delta (float) – Maximum deviation of scale from 1.0 (default 0.1).

  • max_scale_diff (float) – Maximum allowed |scale_x - scale_y| (default 0.05).

  • close_threshold_px (float) – Initial max NN distance for well-matched pairs (default 30).

  • close_threshold_floor (float) – Tightest threshold allowed (default 5).

  • max_icp_iter (int) – Maximum ICP iterations (default 20).

Returns:

  • warp_refined (ndarray) – 3x3 refined homography.

  • accepted (bool) – True if ICP correction was accepted.

exo2micro.alignment.refine_interior_ecc(post_full, pre_full, warp_init, interior_blur_base=8.0, interior_max_correction=500, interior_min_inlier_ratio=0.4)

Deprecated alias for refine_interior_sift(). The function was renamed because its body uses SIFT, not ECC, after the v2.1 rewrite. Prefer the new name for new code.

exo2micro.alignment.refine_interior_sift(post_full, pre_full, warp_init, interior_blur_base=8.0, interior_max_correction=500, interior_min_inlier_ratio=0.4)[source]

Refine alignment using SIFT feature matching on interior image content.

Detects SIFT features in both post-stain and (ICP-warped) pre-stain images, matches them, and computes a refined homography via RANSAC. This is robust to the intensity differences between pre and post because SIFT features are based on local gradient structure.

Microbe-only features (present in post but not pre) are naturally rejected by the matching + RANSAC pipeline as outliers.

This function was previously called refine_interior_ecc when the body used an ECC pyramid (pre-v2.1). The implementation now uses SIFT exclusively; the old name has been retained as an alias for one version for backward compatibility.

Parameters:

  • post_full (ndarray) – Full-resolution post-stain image (float32).

  • pre_full (ndarray) – Full-resolution pre-stain image (float32, un-warped).

  • warp_init (ndarray) – 3×3 homography from upstream alignment (boundary corr + ICP).

  • interior_blur_base (float) – Gaussian blur sigma applied before feature detection (default 8.0). Suppresses microbe-scale features to focus on mineral grain structure.

  • interior_max_correction (float) – Maximum allowed total correction in full-resolution pixels (default 500). If exceeded, the refinement is rejected.

  • interior_min_inlier_ratio (float) – Minimum RANSAC inlier ratio to accept the refinement (default 0.4). Below this, the match quality is too poor to trust.

Returns:

  • warp_refined (ndarray) – 3×3 refined homography at full resolution.

  • result (dict) – Diagnostic information: - ‘success’ : bool - ‘levels_completed’ : int (1 if success, 0 if not) - ‘total_levels’ : int (always 1) - ‘estimated_accuracy_px’ : float - ‘level_details’ : list of dict - ‘failure_reason’ : str or None

exo2micro.alignment.register_highorder(post_im, pre_im, stopit=500, stopdelta=1e-06, down_scale=0.3, usharp=False, gauss_sigma=0, use_edges=True, boundary_width=15, boundary_smooth=10, coarse_stopit=1000, coarse_stopdelta=0.0001, rotation_search=True, angle_range=20, angle_step=1, scale_search=True, scale_min=0.85, scale_max=1.15, scale_step=0.05, multiscale=True, fine_ecc=False, max_translation=200, max_rotation=5.0, max_scale_delta=0.2, max_scale_diff=0.15, save_prefix=None)[source]

Register pre-stain to post-stain using a multiscale strategy.

Pipeline:

  1. Boundary correlation coarse pass (translation + rotation + scale)

  2. ICP affine refinement of boundary contour correspondences

  3. Optional fine homography ECC pass (fine_ecc=True)

Parameters:

  • post_im (ndarray) – Post-stain (fixed) and pre-stain (moving) images (2D).

  • pre_im (ndarray) – Post-stain (fixed) and pre-stain (moving) images (2D).

  • stopit (int) – Max ECC iterations for fine pass (default 500).

  • stopdelta (float) – ECC convergence threshold (default 1e-6).

  • down_scale (float) – Downsample factor for fine ECC pass (default 0.3).

  • usharp (float or False) – Unsharp mask sigma (default False).

  • gauss_sigma (float) – Gaussian pre-smoothing sigma (default 0).

  • use_edges (bool) – Extract boundary rings for ECC (default True).

  • boundary_width (int) – Boundary ring thickness (default 15).

  • boundary_smooth (float) – Boundary softening sigma (default 10).

  • rotation_search (bool) – Search over rotations (default True).

  • angle_range (float) – Rotation search ±degrees (default 20).

  • angle_step (float) – Rotation search step (default 1).

  • scale_search (bool) – Search over scale factors (default True).

  • scale_min (float) – Scale search parameters.

  • scale_max (float) – Scale search parameters.

  • scale_step (float) – Scale search parameters.

  • multiscale (bool) – Run coarse+ICP pipeline (default True).

  • fine_ecc (bool) – Run fine ECC after ICP (default False).

  • max_translation (float) – ICP sanity limits.

  • max_rotation (float) – ICP sanity limits.

  • max_scale_delta (float) – ICP scale sanity limits.

  • max_scale_diff (float) – ICP scale sanity limits.

  • save_prefix (str or None) – If set, save pipeline check plots to disk.

Returns:

  • post_full (ndarray (float32))

  • pre_aligned (ndarray (float32)) – Pre-stain warped by full pipeline.

  • pre_coarse_aligned (ndarray or None) – Pre-stain warped by coarse pass only (None if multiscale=False).

  • warp_matrix (ndarray) – Final 3x3 homography.

  • debug_data (dict) – Intermediate data for pipeline check plots.