Add masked loss support for region-of-interest driven registration

[Copilot]

Enables registration to be driven only by specific regions of interest by computing loss exclusively where masks are non-zero. Both fixed and moving images accept an optional mask channel.

Implementation

• Masked loss variants: CC, MI, FusedCC, FusedMI now support masked=True parameter
  • Last channel treated as mask; remaining channels as image data
  • Mask combination modes: "mult" (element-wise product) or "max"
  • Batch-wise MI processing handles variable mask sizes per sample
• Shared utilities (maskedutils.py): mask extraction, combination, and weighted loss reduction
• Registration integration: All registration classes (Greedy, Affine, Rigid, SYN, Moments) updated
  • loss_type="masked_cc" or "masked_mse" prefix activates masked mode
  • Gaussian smoothing in multi-resolution pipeline applies only to image channels, preserving mask
• Helper functions: generate_image_mask_allones() and apply_mask_to_image() for easy mask channel concatenation

Usage

from fireants.io.imagemask import apply_mask_to_image, generate_image_mask_allones
from fireants.registration.greedy import GreedyRegistration

# Append mask as last channel (shape: [N, C+1, ...])
fixed_with_mask = apply_mask_to_image(fixed_img, generate_image_mask_allones(fixed_img))
moving_with_mask = apply_mask_to_image(moving_img, roi_mask)

reg = GreedyRegistration(
    scales=[2, 1],
    iterations=[100, 50],
    fixed_images=BatchedImages([fixed_with_mask]),
    moving_images=BatchedImages([moving_with_mask]),
    loss_type="masked_cc",  # masked variant
    optimizer_lr=0.5
)

Testing

• 2D and 3D masked registration fidelity tests
• Synthetic data: axis-aligned vs rotated squares with diagonal half-plane mask
• Documentation with visual comparisons of masked vs unmasked results

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.