Source code for medical_image.algorithms.deep_segmentation

# SPDX-License-Identifier: AGPL-3.0-only
#
# Copyright (C) 2024-2026 [YOUR NAME / ORGANIZATION]
#
# This file is part of medical-image-std.
#
# medical-image-std is free software: you can redistribute it and/or
# modify it under the terms of the GNU Affero General Public License
# as published by the Free Software Foundation, either version 3 of
# the License, or (at your option) any later version.
#
# medical-image-std is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with medical-image-std. If not, see
# <https://www.gnu.org/licenses/>.

"""
Generic deep-learning segmentation algorithm.

Wraps any trained segmentation model as an :class:`Algorithm` subclass.
Output follows Option 2: binary mask on ``output.pixel_data`` + per-lesion
:class:`Annotation` objects on ``output.annotations``.
"""

import logging
import re
from pathlib import Path
from typing import Optional

import numpy as np
import requests
import torch
import torch.nn as nn
from scipy import ndimage
from skimage.exposure import equalize_adapthist
from skimage.measure import find_contours

from medical_image.algorithms.algorithm import Algorithm
from medical_image.data.annotation import Annotation, GeometryType
from medical_image.data.image import Image
from medical_image.data.in_memory_image import InMemoryImage
from medical_image.process.mammography import MammographyPreprocessing
from medical_image.utils.device import Precision

try:
    import cv2
except ImportError:  # pragma: no cover - optional at import time
    cv2 = None

logger = logging.getLogger(__name__)

# Patches per forward call are sized to a fixed pixel budget rather than a fixed
# count: the served checkpoints use patch sizes from 32 to 256, and a batch of
# eight 32x32 patches is a 32 KB tensor issued thousands of times, where
# per-call overhead dwarfs the arithmetic.
DEFAULT_BATCH_PIXELS = 8 * 512 * 512

DEFAULT_MODEL_SERVER_URL = "https://mcdmodels.ptm.tn/"
DEFAULT_CACHE_DIR = Path.home() / ".cache" / "medical-std" / "models"

KNOWN_ARCHITECTURES = {"unet", "attention_unet", "unetpp", "deeplabv3p"}
KNOWN_LOSSES = {"bce_dice", "focal_dice", "topk_bce_dice", "focal_tversky"}
KNOWN_DATASETS = {"inbreast", "cbis_ddsm_new"}

_MODEL_NAME_PATTERN = re.compile(
    r"^(attention_unet|deeplabv3p|unetpp|unet)"
    r"_(bce_dice|focal_dice|topk_bce_dice|focal_tversky)"
    r"_(\d+)"
    r"_(inbreast|cbis_ddsm_new)"
    r"(_clahe)?$"
)


class _OnnxModel:
    """Adapter presenting an ONNX Runtime session as a callable torch module.

    Keeps the inference loop free of backend branching: it still calls
    ``self.model(tensor)`` and still gets logits back.
    """

    def __init__(self, path: str, providers: Optional[list] = None, threads: int = 0):
        import onnxruntime as ort

        options = ort.SessionOptions()
        options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
        if threads:
            options.intra_op_num_threads = threads
        self.session = ort.InferenceSession(
            path, options, providers=providers or ["CPUExecutionProvider"]
        )
        self.input_name = self.session.get_inputs()[0].name

    def __call__(self, x: torch.Tensor) -> torch.Tensor:
        array = x.detach().cpu().contiguous().numpy()
        return torch.from_numpy(self.session.run(None, {self.input_name: array})[0])

    def to(self, *args, **kwargs) -> "_OnnxModel":
        return self

    def eval(self) -> "_OnnxModel":
        return self


def _parse_model_name(name: str) -> Optional[dict]:
    """Parse a model directory name into metadata dict, or None if invalid."""
    m = _MODEL_NAME_PATTERN.match(name)
    if not m:
        return None
    return {
        "name": name,
        "architecture": m.group(1),
        "loss": m.group(2),
        "patch_size": int(m.group(3)),
        "dataset": m.group(4),
        "uses_clahe": m.group(5) is not None,
    }


[docs] class DeepSegmentationAlgorithm(Algorithm): """Run a trained segmentation model as a framework Algorithm. After :meth:`apply`, the following attributes are populated: * ``probability_map`` — ``(H, W)`` float tensor in [0, 1]. * ``lesion_count`` — number of detected lesions after filtering. The ``output`` image receives: * ``pixel_data`` — ``(H, W)`` binary mask (0.0 / 1.0). * ``annotations`` — one :class:`Annotation` per detected lesion (``POLYGON`` contour + metadata with confidence, area, bbox). Construction ------------ Pass **either** ``checkpoint_path`` to load from a saved checkpoint (requires ``segmentation_models_pytorch``), **or** ``model`` to supply any ``nn.Module`` directly. Args: checkpoint_path: Path to a ``.pt`` checkpoint (must contain ``model_state_dict`` and optionally ``config``). model: A pre-built ``nn.Module`` (mutually exclusive with *checkpoint_path*). use_clahe: Whether to apply CLAHE before inference. When loading from checkpoint this is read from ``config.preprocessing.clahe``. patch_size: Sliding-window patch size for inference. stride: Stride between patches (default: ``patch_size // 2``). threshold: Probability threshold for binarisation. min_lesion_area: Minimum connected-component area (pixels) to keep. device: ``"cuda"`` or ``"cpu"`` (auto-detected if ``None``). precision: Mixed-precision mode. crop_to_breast: Restrict inference to the breast bounding box, as the training/validation pipeline does. A mammogram is mostly air, and the model never saw that region during training. breast_margin: Pixels of slack around the breast bounding box. skip_background_patches: Drop patches that lie entirely outside the breast mask. Free once the mask has been computed for the crop. stride_ratio: Overrides the checkpoint's own value. ``0.5`` infers every pixel four times; see ``blend``. blend: ``"gaussian"`` weights a patch's centre above its edges when averaging overlaps, which suppresses seams better than ``"uniform"`` at the same stride — so it is what makes a larger stride viable. batch_pixels: Pixel budget per forward call. channels_last: Use the channels-last memory format, usually faster for convolutions on both oneDNN CPU and CUDA tensor cores. compile_model: Wrap the model in :func:`torch.compile`. The cost is paid once per process and per input shape, which suits a long-lived worker with a fixed patch size. onnx_path: Run inference through ONNX Runtime instead of torch. The checkpoint is still loaded, because it carries the patch size, threshold and CLAHE flag. See :meth:`export_onnx`. onnx_providers: ONNX Runtime execution providers, defaulting to CPU. """
[docs] def __init__( self, checkpoint_path: Optional[str] = None, model: Optional[nn.Module] = None, use_clahe: bool = False, patch_size: int = 512, stride: Optional[int] = None, threshold: float = 0.5, min_lesion_area: int = 4, device: str = None, precision: Precision = Precision.FULL, crop_to_breast: bool = True, breast_margin: int = 30, skip_background_patches: bool = True, stride_ratio: Optional[float] = None, blend: str = "gaussian", batch_pixels: int = DEFAULT_BATCH_PIXELS, channels_last: bool = False, compile_model: bool = False, onnx_path: Optional[str] = None, onnx_providers: Optional[list] = None, ): super().__init__(device=device, precision=precision) if checkpoint_path is None and model is None: raise ValueError("Provide either checkpoint_path or model") if blend not in ("gaussian", "uniform"): raise ValueError(f"blend must be 'gaussian' or 'uniform', got {blend!r}") self.patch_size = patch_size self.stride = stride or patch_size // 2 self.threshold = threshold self.min_lesion_area = min_lesion_area self.use_clahe = use_clahe self.crop_to_breast = crop_to_breast self.breast_margin = breast_margin self.skip_background_patches = skip_background_patches self.blend = blend self.batch_pixels = batch_pixels self._explicit_stride = stride is not None self._stride_ratio_override = stride_ratio self._model_name: Optional[str] = None if checkpoint_path is not None: self._load_from_checkpoint(checkpoint_path) else: self.model = model.to(self.device) self.model.eval() if stride_ratio is not None: self.stride = max(1, int(self.patch_size * stride_ratio)) self.channels_last = channels_last and onnx_path is None if self.channels_last: self.model = self.model.to(memory_format=torch.channels_last) if compile_model and onnx_path is None: self.model = torch.compile(self.model) # Swapped in last: the checkpoint is still what supplies patch_size, # threshold and the CLAHE flag, so it has to be loaded either way. if onnx_path is not None: self.model = _OnnxModel(onnx_path, providers=onnx_providers) # Populated after apply() self.probability_map: Optional[torch.Tensor] = None self.lesion_count: int = 0 self.breast_bbox: Optional[tuple] = None self.patches_inferred: int = 0 self.patches_skipped: int = 0
# ------------------------------------------------------------------ # Remote model support # ------------------------------------------------------------------
[docs] @classmethod def list_available_models(cls, server_url: str = None) -> list[dict]: """Query the model server and return metadata for each available model. Returns a list of dicts with keys: name, architecture, loss, patch_size, dataset, uses_clahe, url. """ url = (server_url or DEFAULT_MODEL_SERVER_URL).rstrip("/") + "/" resp = requests.get(url, timeout=30) resp.raise_for_status() html = resp.text # Extract href links ending with / dirs = re.findall(r'href="([^"]+/)"', html) models = [] for d in dirs: dirname = d.rstrip("/") if dirname in (".", "..") or dirname.startswith("?"): continue info = _parse_model_name(dirname) if info is not None: info["url"] = url + dirname + "/" models.append(info) return models
[docs] @classmethod def from_pretrained( cls, model_name: str, server_url: str = None, cache_dir: str = None, device: str = None, precision: Precision = Precision.FULL, force_download: bool = False, **kwargs, ) -> "DeepSegmentationAlgorithm": """Download a pretrained model from the server and return a ready-to-use algorithm. Extra keyword arguments are forwarded to the constructor, so inference tuning (``stride_ratio``, ``blend``, ``crop_to_breast``, …) survives the checkpoint round-trip. """ base_url = (server_url or DEFAULT_MODEL_SERVER_URL).rstrip("/") checkpoint_url = f"{base_url}/{model_name}/best_model.pt" cache = Path(cache_dir) if cache_dir else DEFAULT_CACHE_DIR local_path = cache / model_name / "best_model.pt" if not local_path.exists() or force_download: local_path.parent.mkdir(parents=True, exist_ok=True) logger.info("Downloading %s -> %s", checkpoint_url, local_path) resp = requests.get(checkpoint_url, stream=True, timeout=120) resp.raise_for_status() with open(local_path, "wb") as f: for chunk in resp.iter_content(chunk_size=8192): f.write(chunk) logger.info("Download complete: %s", local_path) algo = cls( checkpoint_path=str(local_path), device=device, precision=precision, **kwargs, ) algo._model_name = model_name return algo
[docs] def export_onnx(self, path: str, opset: int = 17) -> str: """Export the loaded model to ONNX with a dynamic batch axis. The batch axis is dynamic because the pipeline sizes batches from a pixel budget, and the final batch of a run is usually short. Height and width stay static — they are the checkpoint's patch size and never vary. """ if isinstance(self.model, _OnnxModel): raise ValueError( "This instance already runs ONNX; export from a torch one." ) ps = self.patch_size dummy = torch.zeros(1, 1, ps, ps, device=self.device) torch.onnx.export( self.model, dummy, path, input_names=["input"], output_names=["logits"], dynamic_axes={"input": {0: "batch"}, "logits": {0: "batch"}}, opset_version=opset, ) logger.info("Exported ONNX model to %s (patch size %d)", path, ps) return path
@property def model_info(self) -> Optional[dict]: """Return metadata about the loaded model, or None if name unknown.""" if self._model_name is None: return None return _parse_model_name(self._model_name) def _load_from_checkpoint(self, checkpoint_path: str) -> None: """Load model architecture + weights from a training checkpoint. Reads ``config`` from the checkpoint and auto-configures: ``patch_size``, ``use_clahe``, ``threshold``, ``min_lesion_area``, and ``stride`` when they were not explicitly overridden by the caller. """ checkpoint = torch.load( checkpoint_path, map_location=self.device, weights_only=False ) config = checkpoint.get("config", {}) # Auto-configure from checkpoint when constructor used defaults self.use_clahe = config.get("preprocessing", {}).get("clahe", False) patching_cfg = config.get("patching", {}) if patching_cfg.get("patch_size"): self.patch_size = patching_cfg["patch_size"] inference_cfg = config.get("inference", {}) if inference_cfg.get("threshold"): self.threshold = inference_cfg["threshold"] if inference_cfg.get("min_lesion_area"): self.min_lesion_area = inference_cfg["min_lesion_area"] if not self._explicit_stride and self._stride_ratio_override is None: stride_ratio = inference_cfg.get("stride_ratio", 0.5) self.stride = max(1, int(self.patch_size * stride_ratio)) # Defer smp import to here — only needed for checkpoint loading import segmentation_models_pytorch as smp model_cfg = config.get("model", {}) name = model_cfg.get("name", "unet") encoder = model_cfg.get("encoder", "resnet34") in_channels = model_cfg.get("in_channels", 1) common = dict( encoder_name=encoder, encoder_weights=None, in_channels=in_channels, classes=1, activation=None, ) if name == "unet": self.model = smp.Unet(**common) elif name == "attention_unet": self.model = smp.Unet(**common, decoder_attention_type="scse") elif name == "unetpp": self.model = smp.UnetPlusPlus(**common) elif name == "deeplabv3p": self.model = smp.DeepLabV3Plus(**common) else: raise ValueError(f"Unknown model: {name}") self.model.load_state_dict(checkpoint["model_state_dict"]) self.model.to(self.device) self.model.eval() # ------------------------------------------------------------------ # Algorithm interface # ------------------------------------------------------------------
[docs] def apply(self, image: Image, output: Image) -> Image: img = image.pixel_data.float() if img.ndim == 3: img = img.squeeze(0) full_shape = img.shape # Normalize to [0, 1]. The reference pipeline's normalize_bit_depth step # is redundant here: it scales by 2^bits and the caller then divides by # the result's own max, which is algebraically this same division. img_max = img.max() if img_max > 1.0: img = img / img_max breast_mask = self._breast_mask(img) if self.crop_to_breast else None bbox = ( self._mask_bbox(breast_mask, full_shape) if breast_mask is not None else None ) self.breast_bbox = bbox if bbox is not None: y0, x0, y1, x1 = bbox img = img[y0:y1, x0:x1] breast_mask = breast_mask[y0:y1, x0:x1] # CLAHE after the crop, matching the reference pipeline: the transform is # tile-local, so including the air region shifts every tile's histogram. if self.use_clahe: img = self._apply_clahe(img) prob_map = self._infer_patches( img, breast_mask if self.skip_background_patches else None ) if bbox is not None: full = torch.zeros(full_shape, dtype=prob_map.dtype) full[bbox[0] : bbox[2], bbox[1] : bbox[3]] = prob_map prob_map = full # Store probability map self.probability_map = prob_map # Binarize binary_mask = (prob_map > self.threshold).float() # Extract per-lesion annotations (filter by min_lesion_area) annotations = self._extract_annotations( binary_mask, prob_map, self.min_lesion_area ) self.lesion_count = len(annotations) # Set output output.pixel_data = binary_mask output.annotations = [] for ann in annotations: output.add_annotation(ann) return output
# ------------------------------------------------------------------ # Patch inference # ------------------------------------------------------------------ @torch.inference_mode() def _infer_patches( self, image: torch.Tensor, breast_mask: Optional[torch.Tensor] = None, ) -> torch.Tensor: """Sliding-window inference with weighted overlap averaging. Patches are gathered, run and stitched as whole batches rather than one at a time — at a 32 px patch size a full mammogram is over 50,000 of them, and the per-patch Python was costing seconds before any of the arithmetic happened. """ h, w = image.shape ps = self.patch_size # Padding the image up to at least one patch removes the ragged-edge # case entirely, so every patch below is exactly ps x ps and the # gather/scatter can be a single indexing op. pad_h, pad_w = max(0, ps - h), max(0, ps - w) if pad_h or pad_w: image = torch.nn.functional.pad(image, (0, pad_w, 0, pad_h)) if breast_mask is not None: breast_mask = torch.nn.functional.pad(breast_mask, (0, pad_w, 0, pad_h)) ph, pw = image.shape ys, xs = self._patch_positions(ph, pw, ps, self.stride, breast_mask) self.patches_inferred = len(ys) prediction_sum = torch.zeros(ph, pw) weight_sum = torch.zeros(ph, pw) if len(ys) == 0: return prediction_sum[:h, :w] window = self._blend_window(ps) batch = max(1, self.batch_pixels // (ps * ps)) # Two ways to accumulate, and which is cheaper flips with patch size. # A slice assignment per patch costs ~36 us of Python but touches each # pixel once; a batched index_add_ has no per-patch Python but has to # materialise an int64 index per pixel. Trading ~36 us against ps^2 # index writes puts the break-even near ps = 110. scatter = ps <= 128 if scatter: rows = torch.arange(ps) offsets = (rows.view(1, ps, 1) * pw + rows.view(1, 1, ps)).reshape(1, -1) flat_sum = prediction_sum.view(-1) flat_weight = weight_sum.view(-1) for i in range(0, len(ys), batch): by, bx = ys[i : i + batch], xs[i : i + batch] patches = self._gather_patches(image, by, bx, ps, scatter) inp = patches.unsqueeze(1).to(self.device) if self.channels_last: inp = inp.contiguous(memory_format=torch.channels_last) probs = torch.sigmoid(self.model(inp)).squeeze(1).float().cpu() weighted = probs * window if scatter: idx = ((by * pw + bx).view(-1, 1) + offsets).reshape(-1) flat_sum.index_add_(0, idx, weighted.reshape(-1)) flat_weight.index_add_(0, idx, window.expand_as(probs).reshape(-1)) else: for k in range(len(by)): y, x = int(by[k]), int(bx[k]) prediction_sum[y : y + ps, x : x + ps] += weighted[k] weight_sum[y : y + ps, x : x + ps] += window return (prediction_sum / weight_sum.clamp(min=1e-8))[:h, :w] def _patch_positions( self, h: int, w: int, ps: int, stride: int, breast_mask: Optional[torch.Tensor], ) -> tuple: """Top-left corners of every patch, dropping all-background ones. ``unique()`` is load-bearing. Clamping the last few strides to ``h - ps`` maps several of them onto the same corner, and averaging over the resulting duplicates weights those patches by how many strides happened to collapse onto them — a band ``ps`` wide along the bottom and right edges came out over-weighted, reaching an overlap count of 16 where the true maximum is 9. De-duplicating makes every distinct patch count once. """ ys = torch.arange(0, h, stride).clamp(max=h - ps).unique() xs = torch.arange(0, w, stride).clamp(max=w - ps).unique() grid_y, grid_x = torch.meshgrid(ys, xs, indexing="ij") grid_y, grid_x = grid_y.reshape(-1), grid_x.reshape(-1) if breast_mask is None: self.patches_skipped = 0 return grid_y, grid_x # Summed-area table: one O(1) lookup per patch instead of slicing each. integral = torch.zeros(h + 1, w + 1) integral[1:, 1:] = (breast_mask > 0).float().cumsum(0).cumsum(1) covered = ( integral[grid_y + ps, grid_x + ps] - integral[grid_y, grid_x + ps] - integral[grid_y + ps, grid_x] + integral[grid_y, grid_x] ) keep = covered > 0 self.patches_skipped = int((~keep).sum()) return grid_y[keep], grid_x[keep] @staticmethod def _gather_patches( image: torch.Tensor, ys: torch.Tensor, xs: torch.Tensor, ps: int, vectorised: bool, ) -> torch.Tensor: """Stack one batch of patches. Same size/shape either way. Mirrors the accumulation trade-off: advanced indexing avoids per-patch Python but builds an int64 index per pixel, which is the losing side of the deal once a patch is large enough for the Python to disappear. """ if not vectorised: return torch.stack( [ image[int(y) : int(y) + ps, int(x) : int(x) + ps] for y, x in zip(ys, xs) ] ) rows = ys.view(-1, 1, 1) + torch.arange(ps).view(1, ps, 1) cols = xs.view(-1, 1, 1) + torch.arange(ps).view(1, 1, ps) return image[rows, cols] def _blend_window(self, ps: int) -> torch.Tensor: """Per-pixel weight applied to a patch when averaging overlaps. A patch's border pixels are the ones the model had least context for, so weighting them down suppresses seams better than a plain mean — which is what makes a coarser stride viable at the same quality. """ if self.blend == "uniform": return torch.ones(ps, ps) coords = torch.arange(ps, dtype=torch.float32) - (ps - 1) / 2.0 sigma = ps / 8.0 line = torch.exp(-(coords**2) / (2 * sigma**2)) window = torch.outer(line, line) # Never let a weight reach zero: a pixel covered by exactly one patch # would otherwise divide by ~0 and come back as noise. return window.clamp(min=window.max() * 0.1) # ------------------------------------------------------------------ # Annotation extraction # ------------------------------------------------------------------ @staticmethod def _extract_annotations( binary_mask: torch.Tensor, prob_map: torch.Tensor, min_lesion_area: int = 4, ) -> list[Annotation]: """Extract per-lesion Annotations from binary mask via connected components.""" mask_np = binary_mask.numpy().astype(np.uint8) prob_np = prob_map.numpy() labeled, num_components = ndimage.label(mask_np) annotations = [] for i in range(1, num_components + 1): component = (labeled == i).astype(np.uint8) area = int(component.sum()) if area < min_lesion_area: continue # Find contour for polygon using skimage contours = find_contours(component, level=0.5) if not contours: continue # Pick the longest contour contour = max(contours, key=len) # find_contours returns (row, col) — convert to (x, y) contour_pts = [(int(round(c[1])), int(round(c[0]))) for c in contour] # Need >= 3 points for a polygon if len(contour_pts) < 3: ys, xs = np.where(component) x_min, y_min = int(xs.min()), int(ys.min()) x_max, y_max = int(xs.max()), int(ys.max()) ann = Annotation( shape=GeometryType.RECTANGLE, coordinates=[x_min, y_min, x_max, y_max], label="microcalcification", metadata={ "confidence": float(prob_np[component == 1].mean()), "area": area, }, ) else: confidence = float(prob_np[component == 1].mean()) ys, xs = np.where(component) bbox = [int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max())] ann = Annotation( shape=GeometryType.POLYGON, coordinates=contour_pts, label="microcalcification", metadata={ "confidence": confidence, "area": area, "bbox": bbox, }, ) annotations.append(ann) return annotations # ------------------------------------------------------------------ # CLAHE # ------------------------------------------------------------------ @staticmethod def _apply_clahe( image: torch.Tensor, clip_limit: float = 2.0, grid_size: int = 8, ) -> torch.Tensor: """Apply CLAHE preprocessing. Returns float tensor in [0, 1]. Uses OpenCV to match training bit for bit — the checkpoints were built with ``cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))``, where the grid size is a *tile count*. The scikit-image fallback takes its own default ``kernel_size``, which is height/8 x width/8 and so the same 64 tiles; passing ``(8, 8)`` there would instead ask for 8x8-*pixel* tiles — roughly 213,000 of them on a full mammogram, which is both far slower and a different transform from the one the models were trained on. """ img_np = image.detach().cpu().numpy() img_min, img_max = img_np.min(), img_np.max() if img_max - img_min > 0: img_norm = (img_np - img_min) / (img_max - img_min) else: img_norm = np.zeros_like(img_np) if cv2 is not None: clahe = cv2.createCLAHE( clipLimit=clip_limit, tileGridSize=(grid_size, grid_size) ) enhanced = clahe.apply((img_norm * 255).astype(np.uint8)) return torch.from_numpy(enhanced.astype(np.float32) / 255.0) logger.warning( "OpenCV unavailable — falling back to scikit-image CLAHE, which is " "an approximation of the transform used during training." ) enhanced = equalize_adapthist(img_norm, clip_limit=0.02) return torch.from_numpy(enhanced.astype(np.float32)) # ------------------------------------------------------------------ # Breast region # ------------------------------------------------------------------ def _breast_mask(self, image: torch.Tensor) -> Optional[torch.Tensor]: """Binary breast mask, or None if it could not be computed. A failure here must not fail the request: the mask is an optimisation plus a training-parity step, and falling back to the whole frame is the old behaviour rather than an error. """ try: src = InMemoryImage(array=image) out = MammographyPreprocessing.breast_mask(src, device="cpu") mask = out.pixel_data if mask.ndim == 3: mask = mask.squeeze(0) return mask.detach().cpu() except Exception as exc: # pragma: no cover - defensive logger.warning("Breast mask failed, using the full frame: %s", exc) return None def _mask_bbox(self, mask: torch.Tensor, shape: tuple) -> Optional[tuple]: """Bounding box of the mask as (y0, x0, y1, x1), with margin applied.""" nonzero = torch.nonzero(mask > 0) if nonzero.numel() == 0: return None h, w = shape margin = self.breast_margin y_min, x_min = nonzero.min(dim=0).values.tolist() y_max, x_max = nonzero.max(dim=0).values.tolist() bbox = ( max(0, y_min - margin), max(0, x_min - margin), min(h, y_max + 1 + margin), min(w, x_max + 1 + margin), ) if bbox[2] - bbox[0] <= 0 or bbox[3] - bbox[1] <= 0: return None return bbox