A utility function to generate sampling points

[wyli]

Is your feature request related to a problem? Please describe.
Currently there are a few functions in monai.transforms to help sampling image patches:

1. map_classes_to_indices to identify all feasible sampling indices
2. generate_label_classes_crop_centers to subsample and generate spatial coordinates
3. RandCropByLabelClasses combines 1, 2 and output image patches

Describe the solution you'd like

Would be great to have a helper function to run step 1 and 2 as a single command. The function should output sampling coordinates instead of the final patch

Describe alternatives you've considered

Write the logic with multiple commands: https://gist.github.com/wyli/50c65e686beaf418a32c9cc131f0bdc7

Same idea applies to the other sampling transforms such as RandCropByPosNegLabel

[Yu0610]

I wrote this helper function with the expectation that the output would be the coordinates of the centers. I hope it meets your requirements.

def combineMCtIandGLCCC(
    label: NdarrayOrTensor,
    spatial_size: Sequence[int] | int,
    num_samples: int,
    label_spatial_shape: Sequence[int],
    indices: Sequence[NdarrayOrTensor],
    num_classes: int | None = None,
    image: NdarrayOrTensor | None = None,
    image_threshold: float = 0.0,
    max_samples_per_class: int | None = None,
    ratios: list[float | int] | None = None,
    rand_state: np.random.RandomState | None = None,
    allow_smaller: bool = False,
    warn: bool = True,
) -> list[NdarrayOrTensor]:
    """
    Combine "map_classes_to_indices" and "generate_pos_neg_label_crop_centers" functions, return crop center coordinates.
     Args:
        spatial_size: spatial size of the ROIs to be sampled.
        num_samples: total sample centers to be generated.
        pos_ratio: ratio of total locations generated that have center being foreground.
        label_spatial_shape: spatial shape of the original label data to unravel selected centers.
        fg_indices: pre-computed foreground indices in 1 dimension.
        bg_indices: pre-computed background indices in 1 dimension.
        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).
        label: use the label data to get the indices of every class.
        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.    
        
        Raises:
        ValueError: When the proposed roi is larger than the image.
        ValueError: When the foreground and background indices lengths are 0.
    """

    indices_ = indices if indices is None else indices
    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, MetaTensor) else label.shape[1:]
    elif image is not None:
        _shape = image.peek_pending_shape() if isinstance(image, 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 centers

[vikashg]

@Yu0610 can you start a PR ?