Repository: Project-MONAI/MONAI
File: monai/transforms/utils.py (Python)

Code before:
        label: use the label data to get the indices of every class.
        spatial_size: spatial size of the ROIs to be sampled.
        num_samples: total sample centers to be generated.
        label_spatial_shape: spatial shape of the original label data to unravel selected centers.
        indices: sequence of pre-computed foreground indices of every class in 1 dimension.
        num_classes: number of classes for argmax label, not necessary for One-Hot label.
        image: if image is not None, only return the indices of every class that are within the valid
            region of the image (``image > image_threshold``).
        image_threshold: if enabled `image`, use ``image > image_threshold`` to
            determine the valid image content area and select class indices only in this area.
        max_samples_per_class: maximum length of indices in each class to reduce memory consumption.
            Default is None, no subsampling.
        ratios: ratios of every class in the label to generate crop centers, including background class.
            if None, every class will have the same ratio to generate crop centers.
        rand_state: numpy randomState object to align with other modules.
        allow_smaller: if `False`, an exception will be raised if the image is smaller than
            the requested ROI in any dimension. If `True`, any smaller dimensions will be set to
            match the cropped size (i.e., no cropping in that dimension).
        warn: if `True` prints a warning if a class is not present in the label.
    Returns:
        Tuple of crop centres
    """
    if indices is None:
        if label is None:
            raise ValueError("label must not be None.")
        indices = map_classes_to_indices(label, num_classes, image, image_threshold, max_samples_per_class)

    _shape = None
    if label is not None:
        _shape = label.peek_pending_shape() if isinstance(label, monai.data.MetaTensor) else label.shape[1:]
    elif image is not None:
        _shape = image.peek_pending_shape() if isinstance(image, monai.data.MetaTensor) else image.shape[1:]

    if _shape is None:
        raise ValueError("label or image must be provided to infer the output spatial shape.")

    centers = generate_label_classes_crop_centers(
        spatial_size, num_samples, _shape, indices, ratios, rand_state, allow_smaller, warn
    )

    return ensure_tuple(centers)


def map_binary_to_indices(
    label: NdarrayOrTensor, image: NdarrayOrTensor | None = None, image_threshold: float = 0.0
) -> tuple[NdarrayOrTensor, NdarrayOrTensor]:
    """
    Compute the foreground and background of input label data, return the indices after fattening.
    For example:
    ``label = np.array([[[0, 1, 1], [1, 0, 1], [1, 1, 0]]])``
    ``foreground indices = np.array([1, 2, 3, 5, 6, 7])`` and ``background indices = np.array([0, 4, 8])``

Review comment (suggestion):
```suggestion
    indices = map_classes_to_indices(label, num_classes, image, image_threshold, max_samples_per_class)
```

Code after:
        label: use the label data to get the indices of every class.
        spatial_size: spatial size of the ROIs to be sampled.
        num_samples: total sample centers to be generated.
        label_spatial_shape: spatial shape of the original label data to unravel selected centers.
        indices: sequence of pre-computed foreground indices of every class in 1 dimension.
        num_classes: number of classes for argmax label, not necessary for One-Hot label.
        image: if image is not None, only return the indices of every class that are within the valid
            region of the image (``image > image_threshold``).
        image_threshold: if enabled `image`, use ``image > image_threshold`` to
            determine the valid image content area and select class indices only in this area.
        max_samples_per_class: maximum length of indices in each class to reduce memory consumption.
            Default is None, no subsampling.
        ratios: ratios of every class in the label to generate crop centers, including background class.
            if None, every class will have the same ratio to generate crop centers.
        rand_state: numpy randomState object to align with other modules.
        allow_smaller: if `False`, an exception will be raised if the image is smaller than
            the requested ROI in any dimension. If `True`, any smaller dimensions will be set to
            match the cropped size (i.e., no cropping in that dimension).
        warn: if `True` prints a warning if a class is not present in the label.
    Returns:
        Tuple of crop centres
    """
    if label is None:
        raise ValueError("label must not be None.")
    indices = map_classes_to_indices(label, num_classes, image, image_threshold, max_samples_per_class)

    if label_spatial_shape is not None:
        _shape = label_spatial_shape
    elif isinstance(label, monai.data.MetaTensor):
        _shape = label.peek_pending_shape()
    else:
        _shape = label.shape[1:]

    if _shape is None:
        raise ValueError(
            "label_spatial_shape or label with a known shape must be provided to infer the output spatial shape."
        )
    centers = generate_label_classes_crop_centers(
        spatial_size, num_samples, _shape, indices, ratios, rand_state, allow_smaller, warn
    )

    return ensure_tuple(centers)


def map_binary_to_indices(
    label: NdarrayOrTensor, image: NdarrayOrTensor | None = None, image_threshold: float = 0.0
) -> tuple[NdarrayOrTensor, NdarrayOrTensor]:
    """
    Compute the foreground and background of input label data, return the indices after fattening.
    For example:
    ``label = np.array([[[0, 1, 1], [1, 0, 1], [1, 1, 0]]])``