AlbumentationsX 2.3.3: pass the 2.5D stack through images=imgls

[ternaus]

Hi,

Albumentations keeps one sampled augmentation aligned across all 2.5D images in this third-place RSNA solution. I maintain the library, and I am glad it was useful here.

The README describes the core data layout: 96 DICOM slices become 32 three-channel images, and the same augmentation is applied across the study.

The whole-study dataset reserves image0...image499 in each pipeline:

def create_valid_transforms(cfg):
    return A.Compose([
        A.Resize(*cfg.imagesize, p=1), # interpolation = cv2.INTER_CUBIC,
        A.Normalize(mean=cfg.norm_mean[:],
                    std=cfg.norm_std[:], p=1.0),
        ToTensorV2()
        ],
    additional_targets=dict((f'image{i}', 'image') for i in range(500)))

def create_valid_transforms_no_norm(cfg):
    return A.Compose([
        A.Resize(*cfg.imagesize, p=1), # interpolation = cv2.INTER_CUBIC,
        ToTensorV2()
        ],
    additional_targets=dict((f'image{i}', 'image') for i in range(500)))

It then turns the variable-length imgls list into named inputs and reconstructs the tensor after augmentation:

imgls = [cv2.merge(img_cropls[i:i + 3]) for i in range(0, len(img_cropls), 3)]

aug_input = dict((f'image{t}', i) for t,i in enumerate(imgls))
aug_input['image'] = imgls[0]
aug_output = self.transform(**aug_input)

out = {'image': torch.stack([aug_output[f'image{t}'] for t,i in enumerate(imgls)])}

The same registry, named-input construction, and reconstruction appear in ds_dh_seg_2C.py, ds_dh_seg_2D.py, ds_dh_seg_2E.py, ds_dh_seg_2H.py, and ds_dh_fracseg_3A_crop.py. Their call sites use the same aug_input → aug_output → torch.stack flow.

Each item in imgls is a separate three-channel 2.5D image, and the downstream model keeps N as its sequence axis. AlbumentationsX 2.3.3 therefore maps this data model to the native plural images target. Passing one 3N-channel image would change that model layout.

For example, the complete validation pipeline becomes:

def create_valid_transforms(cfg):
    return A.Compose([
        A.Resize(
            height=cfg.imagesize[0],
            width=cfg.imagesize[1],
            p=1,
        ),
        A.Normalize(
            mean=cfg.norm_mean[:],
            std=cfg.norm_std[:],
            p=1.0,
        ),
        ToTensorV2(),
    ])

The dataset path becomes:

imgls = np.stack(
    [cv2.merge(img_cropls[i:i + 3]) for i in range(0, len(img_cropls), 3)]
)
aug_output = self.transform(images=imgls)
out = {"image": aug_output["images"]}

ToTensorV2 handles the plural target and returns aug_output["images"] directly as (N, C, H, W), so the replacement does not need another torch.stack.

I tested the named-target and images=imgls routes against the published AlbumentationsX 2.3.3 tag. They were element-for-element identical with torch.float32 output for the configured N=32 sequence, 12 seeded runs through a 2.3.3 form of the training pipeline using the published configuration values, and variable lengths N=1, 37, and 500. I also exercised the plural path at the published 512×512 spatial size and received (1, 3, 512, 512). The shared-parameter behavior is documented in the sequence guide and images target reference.

The repository pins albumentations==1.2.1, so I did not open a dependency-change PR. A complete 2.3.3 migration also needs the training pipeline reviewed: RandomContrast is replaced by RandomBrightnessContrast with a zero brightness_range; Cutout maps to CoarseDropout; ShiftScaleRotate uses shift_range, scale_range, rotate_range, and fill; GridDistortion uses distort_range; and ElasticTransform no longer has alpha_affine. Those changes should be checked against the training distribution and saved model preprocessing.

pip uninstall albumentations
pip install -U albumentationsx

The Python module name stays albumentations, so the existing import albumentations as A and from albumentations.pytorch import ToTensorV2 imports keep the same module path.

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

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.