[Enhancement] Use the built-in min-max normalization mode in Quick Start

[ternaus]

Hi,

The Quick Start can now use the built-in min-max mode in AlbumentationsX 2.3.5 instead of carrying a separate transform for its documented default.

The current example installs the legacy package and imports MinMaxNormalization:

pip install cellseg-models-pytorch
pip install albumentations

from albumentations import Resize, Compose
from cellseg_models_pytorch.models.cellpose import CellPose
from cellseg_models_pytorch.utils import FileHandler
from cellseg_models_pytorch.transforms.albu_transforms import MinMaxNormalization

# intialize nuclei segmentation model trained on HGSC data
# see models in https://huggingface.co/csmp-hub
model = CellPose.from_pretrained(weights="hgsc_v1_efficientnet_b5")

model.set_inference_mode()

# Resize to multiple of 32 of your own choosing
transform = Compose([Resize(1024, 1024), MinMaxNormalization()])

im = FileHandler.read_img(IMG_PATH)
im = transform(image=im)["image"]

With the default amin=0.0 and amax=1.0, MinMaxNormalization.apply forwards the image to the project helper:

def apply(self, image: np.ndarray, **kwargs) -> np.ndarray:
    """Apply min-max normalization.

    Parameters:
        image (np.ndarray):
            Input image to be normalized. Shape (H, W, C)|(H, W).

    Returns:
        np.ndarray:
            Normalized image. Same shape as input. dtype: float32.
    """
    return minmax_normalize(image, self.amin, self.amax, self.copy)

The helper implementation performs global min-max scaling through OpenCV:

return cv2.normalize(
    im.astype(np.float32), None, alpha=amin, beta=amax, norm_type=cv2.NORM_MINMAX
)

Normalize has the same global [0, 1] mode, so the Quick Start replacement is:

from albumentations import Compose, Normalize, Resize
from cellseg_models_pytorch.models.cellpose import CellPose
from cellseg_models_pytorch.utils import FileHandler

# intialize nuclei segmentation model trained on HGSC data
# see models in https://huggingface.co/csmp-hub
model = CellPose.from_pretrained(weights="hgsc_v1_efficientnet_b5")

model.set_inference_mode()

# Resize to multiple of 32 of your own choosing
transform = Compose([Resize(1024, 1024), Normalize(normalization="min_max")])

im = FileHandler.read_img(IMG_PATH)
im = transform(image=im)["image"]

I tested the repository's real minmax_normalize function from commit 8deead255420b4a581e45d12fa471478d0509b42 against the published albumentationsx==2.3.5 wheel and matching tag. The outputs were element-for-element equal, with maximum absolute difference 0, for 37×53 grayscale, RGB, and five-channel uint8 inputs; grayscale and RGB float32 inputs; and constant RGB inputs in both dtypes. Both paths returned the same shape as float32 and left the input unchanged.

The same normalization="min_max" option exists in the frozen MIT release albumentations==2.0.8, but I would not call that path an exact replacement for this helper: with the same uint8 cases it returned float64 and differed by up to 4.51e-7, while the project contract and the 2.3.5 result are float32.

This replacement covers the Quick Start's default [0, 1] range. The project helper still carries distinct behavior for non-default amin and amax, and PercentileNormalization is a separate operation, so I would keep those paths unless their public contract changes.

The README currently asks users to install the MIT-licensed legacy albumentations package, and pyproject.toml does not declare Albumentations as a dependency, so I did not open a package-change PR. If the maintained package and its license are a fit, the switch is:

pip uninstall albumentations
pip install -U albumentationsx

The Python module name remains albumentations, so the direct imports in the example keep the same module path.

The packages use different licenses: the legacy albumentations package is MIT, while albumentationsx==2.3.5 is AGPL-3.0-only. The license guide explains the terms. Albumentations, LLC also offers commercial licenses with alternative terms.

I am glad Albumentations is part of the public Quick Start for this cell-segmentation library. If you have feedback, complaints, or proposals for AlbumentationsX, please open an issue. I read the tracker every day.

If this note is useful, a star or sponsorship would mean a lot.