Add Transform

Add Transform

Use this workflow for architectural choices and coverage. Pre-commit owns fixed API and style conventions; read its diagnostic instead of maintaining a parallel checklist here.

1. Choose the right module

Put the transform in the most specific matching subpackage:

• albumentations/augmentations/geometric/ — spatial transforms (flip, rotate, warp, etc.)
• albumentations/augmentations/pixel/ — pixel-level (color, brightness, noise, etc.)
• albumentations/augmentations/dropout/ — masking/dropout
• albumentations/augmentations/blur/ — blurring
• albumentations/augmentations/crops/ — cropping
• albumentations/augmentations/mixing/ — multi-image mixing
• albumentations/augmentations/medical/ — medical acquisition artifacts and histology stain transforms
• albumentations/augmentations/transforms3d/ — 3D/volume
• albumentations/augmentations/other/ — everything else

2. Functional layer first

Read ../performance-optimization/SKILL.md and its required reference completely before implementing the functional kernel.

Implement the operation in the corresponding functional module, without transform state or invocation sampling.

• Keep the functional layer deterministic; define stochastic behavior at the transform sampling boundary.
• Use the performance workflow to compare kernels, remove redundant work, and check Albucore ownership.
• Use @uint8_io / @float32_io on the owning functional operation when dtype conversion is needed.

3. Write the transform class

• Read Generated Transform Target Contracts before declaring transform support. For every concrete public transform, its Targets: docstring, effective _targets, and active dispatch keys describe the same behavior. A working inherited handler counts; a stub does not. Declare images and masks independently because batch support does not follow from image or mask.
• _targets is the only source for active dispatch. Do not infer targets from method names or add an automatic route for user_data; it is passthrough unless a custom transform explicitly declares and implements that target.
• Read Instance and Frame Binding when a transform supports batches or structured per-frame annotations. Compose(frame_binding=...) owns those relationships; a leaf transform should use the shared dispatch path instead of unpacking frame dictionaries itself.
• Define sampling and replay behavior at the sample_parameters boundary. Implement the greenfield sample_parameters(params, data, targets, sampling) -> SampledParams contract; return SampledParams(params={...}) for values used by every target and use actual-key TargetParams entries for representation-dependent values. The coding guidance document describes the complete contract and the hook reports mechanical violations.
• Use relative parameters where users should transfer a policy across image sizes.
• Use ImageType for image, mask, and volume signatures; reserve np.ndarray for bboxes and keypoints.
• NumPy inputs inside transform execution have explicit channel-last layouts: (H, W, C), (N, H, W, C), and (D, H, W, C); grayscale is (H, W, 1). Compose normalizes public channel-free inputs before dispatch. Native Tensor handlers use the channel-first layouts in NumPy and Tensor routing.
• Keep reusable pixel arithmetic in functional.py, not in a transform class.

4. Add batch optimization (apply_to_images)

Override apply_to_images only when measurement shows an advantage over the default per-image loop. Keep the method as a thin dispatcher with explicit sampled parameters. Put the complete batch operation in a functional helper: shared kernel or LUT setup, direct batch indexing, empty-batch handling, and any preallocated per-image loop.

Keep batch and channel axes distinct; do not reshape (N, H, W, 1) into (H, W, N) to make one OpenCV call. Use Benchmark to compare the direct operation and public Compose route.