hdSrSSKJr SSKJrJrJrJrJr SSK r SSK J r J r Jr SSKJr SSKJr SSKJr SSKJr SS KJrJr SS KJrJr SS KJr /S Qr S r!"SS\5r""SS\"5r#"SS\"5r$"SS\5r%"SS\%5r&"SS\%5r'"SS\5r("SS\5r)g)aModule containing 3D transformation classes for volumetric data augmentation. This module provides a collection of transformation classes designed specifically for 3D volumetric data (such as medical CT/MRI scans). These transforms can manipulate properties such as spatial dimensions, apply dropout effects, and perform symmetry operations on 3D volumes, masks, and keypoints. Each transformation inherits from a base transform interface and implements specific 3D augmentation logic. ) annotations) AnnotatedAnyLiteralUnioncastN)AfterValidatorfield_validatormodel_validator)Self) functional)KeypointsProcessor)check_range_bounds nondecreasing)BaseTransformInitSchema Transform3D)Targets) CenterCrop3DCoarseDropout3D CubicSymmetryPad3D PadIfNeeded3D RandomCrop3Dc^\rSrSrSr\R \R\R4r "SS\ R5r S S U4Sjjjr S Sjr S SjrSSjrS rU=r$) BasePad3DaJ Base class for 3D padding transforms. This class serves as a foundation for all 3D transforms that perform padding operations on volumetric data. It provides common functionality for padding 3D volumes, masks, and processing 3D keypoints during padding operations. The class handles different types of padding values (scalar or per-channel) and provides separate fill values for volumes and masks. Args: fill (tuple[float, ...] | float): Value to fill the padded voxels for volumes. Can be a single value for all channels or a tuple of values per channel. fill_mask (tuple[float, ...] | float): Value to fill the padded voxels for 3D masks. Can be a single value for all channels or a tuple of values per channel. p (float): Probability of applying the transform. Default: 1.0. Targets: volume, mask3d, keypoints Note: This is a base class and not intended to be used directly. Use its derivatives like Pad3D or PadIfNeeded3D instead, or create a custom padding transform by inheriting from this class. Examples: >>> import numpy as np >>> import albumentations as A >>> >>> # Example of a custom padding transform inheriting from BasePad3D >>> class CustomPad3D(A.BasePad3D): ... def __init__(self, padding_size: tuple[int, int, int] = (5, 5, 5), *args, **kwargs): ... super().__init__(*args, **kwargs) ... self.padding_size = padding_size ... ... def get_params_dependent_on_data(self, params: dict[str, Any], data: dict[str, Any]) -> dict[str, Any]: ... # Create symmetric padding: same amount on all sides of each dimension ... pad_d, pad_h, pad_w = self.padding_size ... padding = (pad_d, pad_d, pad_h, pad_h, pad_w, pad_w) ... return {"padding": padding} >>> >>> # Prepare sample data >>> volume = np.random.randint(0, 256, (10, 100, 100), dtype=np.uint8) # (D, H, W) >>> mask3d = np.random.randint(0, 2, (10, 100, 100), dtype=np.uint8) # (D, H, W) >>> keypoints = np.array([[20, 30, 5], [60, 70, 8]], dtype=np.float32) # (x, y, z) >>> keypoint_labels = [1, 2] # Labels for each keypoint >>> >>> # Use the custom transform in a pipeline >>> transform = A.Compose([ ... CustomPad3D( ... padding_size=(2, 10, 10), ... fill=0, ... fill_mask=1, ... p=1.0 ... ) ... ], keypoint_params=A.KeypointParams(format='xyz', label_fields=['keypoint_labels'])) >>> >>> # Apply the transform >>> transformed = transform( ... volume=volume, ... mask3d=mask3d, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # Get the transformed data >>> transformed_volume = transformed["volume"] # Shape: (14, 120, 120) >>> transformed_mask3d = transformed["mask3d"] # Shape: (14, 120, 120) >>> transformed_keypoints = transformed["keypoints"] # Keypoints shifted by padding offsets >>> transformed_keypoint_labels = transformed["keypoint_labels"] # Labels remain unchanged c*\rSrSr%S\S'S\S'Srg)BasePad3D.InitSchemaituple[float, ...] | floatfill fill_maskN__name__ __module__ __qualname____firstlineno____annotations____static_attributes__r$n/var/www/fran/franai/venv/lib/python3.13/site-packages/albumentations/augmentations/transforms3d/transforms.py InitSchemaris'',,r,r.c8>[TU]US9 XlX lgN)p)super__init__r"r#)selfr"r#r1 __class__s r-r3BasePad3D.__init__ms 1 "r,c RUS:XaU$[R"UUURS9$)aApply padding to a 3D volume. Args: volume (np.ndarray): Input volume with shape (depth, height, width) or (depth, height, width, channels) padding (tuple[int, int, int, int, int, int]): Padding values in format: (depth_front, depth_back, height_top, height_bottom, width_left, width_right) **params (Any): Additional parameters Returns: np.ndarray: Padded volume with same number of dimensions as input rrrrrrvolumepaddingvalue)f3dpad_3d_with_paramsr")r4r:r;paramss r-apply_to_volumeBasePad3D.apply_to_volumews2$ ( (M%%))  r,c fUS:XaU$[R"UU[SUR5S9$)aApply padding to a 3D mask. Args: mask3d (np.ndarray): Input mask with shape (depth, height, width) or (depth, height, width, channels) padding (tuple[int, int, int, int, int, int]): Padding values in format: (depth_front, depth_back, height_top, height_bottom, width_left, width_right) **params (Any): Additional parameters Returns: np.ndarray: Padded mask with same number of dimensions as input r8Union[tuple[float, ...], float]r9)r=r>rr#)r4mask3dr;r?s r-apply_to_mask3dBasePad3D.apply_to_mask3ds:$ ( (M%%8$..I  r,c |USn[R"USUSUS/5n[R"X5$)aHApply padding to keypoints. Args: keypoints (np.ndarray): Array of keypoints with shape (num_keypoints, 3+). The first three columns are x, y, z coordinates. **params (Any): Additional parameters containing padding values Returns: np.ndarray: Shifted keypoints with same shape as input r;rnparray fgeometricshift_keypoints)r4 keypointsr?r; shift_vectors r-apply_to_keypointsBasePad3D.apply_to_keypointss@#xxWQZ DE )))BBr,)r"r#rr?)r"r!r#r!r1float)r: np.ndarrayr;#tuple[int, int, int, int, int, int]r?rreturnrV)rDrVr;rWr?rrXrV)rOrVr?rrXrV)r&r'r(r)__doc__rVOLUMEMASK3D KEYPOINTS_targetsrr.r3r@rErQr+ __classcell__r5s@r-rrsFP0A0ABH-[++- +,/0 #'#-#  ##  5     4  5     4CCr,rc|^\rSrSrSr"SS\R 5rSS U4SjjjrS SjrSr U=r $) raB Pad the sides of a 3D volume by specified number of voxels. Args: padding (int, tuple[int, int, int] or tuple[int, int, int, int, int, int]): Padding values. Can be: * int - pad all sides by this value * tuple[int, int, int] - symmetric padding (depth, height, width) where each value is applied to both sides of the corresponding dimension * tuple[int, int, int, int, int, int] - explicit padding per side in order: (depth_front, depth_back, height_top, height_bottom, width_left, width_right) fill (tuple[float, ...] | float): Padding value for image fill_mask (tuple[float, ...] | float): Padding value for mask p (float): probability of applying the transform. Default: 1.0. Targets: volume, mask3d, keypoints Image types: uint8, float32 Note: Input volume should be a numpy array with dimensions ordered as (z, y, x) or (depth, height, width), with optional channel dimension as the last axis. Examples: >>> import numpy as np >>> import albumentations as A >>> >>> # Prepare sample data >>> volume = np.random.randint(0, 256, (10, 100, 100), dtype=np.uint8) # (D, H, W) >>> mask3d = np.random.randint(0, 2, (10, 100, 100), dtype=np.uint8) # (D, H, W) >>> keypoints = np.array([[20, 30, 5], [60, 70, 8]], dtype=np.float32) # (x, y, z) >>> keypoint_labels = [1, 2] # Labels for each keypoint >>> >>> # Create the transform with symmetric padding >>> transform = A.Compose([ ... A.Pad3D( ... padding=(2, 5, 10), # (depth, height, width) applied symmetrically ... fill=0, ... fill_mask=1, ... p=1.0 ... ) ... ], keypoint_params=A.KeypointParams(format='xyz', label_fields=['keypoint_labels'])) >>> >>> # Apply the transform >>> transformed = transform( ... volume=volume, ... mask3d=mask3d, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # Get the transformed data >>> padded_volume = transformed["volume"] # Shape: (14, 110, 120) >>> padded_mask3d = transformed["mask3d"] # Shape: (14, 110, 120) >>> padded_keypoints = transformed["keypoints"] # Keypoints shifted by padding >>> padded_keypoint_labels = transformed["keypoint_labels"] # Labels remain unchanged cR\rSrSr%S\S'\"S5\SSj55rSrg)Pad3D.InitSchema@int | tuple[int, int, int] | tuple[int, int, int, int, int, int]r;c[U[5(aUS:a [S5e[U[5(a"[ SU55(d [S5eU$)aValidate the padding parameter. Args: cls (type): The class object v (int | tuple[int, int, int] | tuple[int, int, int, int, int, int]): The padding value to validate, can be an integer or tuple of integers Returns: int | tuple[int, int, int] | tuple[int, int, int, int, int, int]: The validated padding value Raises: ValueError: If padding is negative or contains negative values rz"Padding value must be non-negativec3Z# UH!n[U[5=(a US:v M# g7f)rN) isinstanceint).0is r- 4Pad3D.InitSchema.validate_padding..s&/YWXRS 1c0B0MqAv0MWXs)+z0Padding tuple must contain non-negative integers)rhri ValueErrortupleall)clsvs r-validate_padding!Pad3D.InitSchema.validate_paddingsR(!S!!a!e !EFF!U##C/YWX/Y,Y,Y !STTHr,r$N)rrrerXre) r&r'r(r)r*r classmethodrsr+r$r,r-r.rcs:QQ  #  O N   $ r,r.cF>[TU]X#US9 XlX lX0lgN)r"r#r1)r2r3r;r"r#)r4r;r"r#r1r5s r-r3Pad3D.__init__s& d1=  "r,c[UR[5(aUR=n=pEX3XDXU4nSU0$[UR5[:XaURup4nX3XDXU4nSU0$URnSU0$)atGet parameters dependent on input data. Args: params (dict[str, Any]): Dictionary of existing parameters data (dict[str, Any]): Dictionary containing input data with volume, mask, etc. Returns: dict[str, Any]: Dictionary containing the padding parameter tuple in format: (depth_front, depth_back, height_top, height_bottom, width_left, width_right) r;)rhr;rilenNUM_DIMENSIONS)r4r?datapad_dpad_hpad_wr;s r-get_params_dependent_on_data"Pad3D.get_params_dependent_on_data#s dllC ( ($(LL 0E 0EU5@G7##  . 0"&,, E%U5@G7##llG7##r,)r"r#r;rS)r;rer"r!r#r!r1rUr?dict[str, Any]r|rrXr r&r'r(r)rYrr.r3rr+r^r_s@r-rrsa:xY))B+,/0 #Q #( #- #  # #$$r,rc^\rSrSrSr"SS\R 5rSS U4SjjjrS SjrSr U=r $) ri;a Pads the sides of a 3D volume if its dimensions are less than specified minimum dimensions. If the pad_divisor_zyx is specified, the function additionally ensures that the volume dimensions are divisible by these values. Args: min_zyx (tuple[int, int, int] | None): Minimum desired size as (depth, height, width). Ensures volume dimensions are at least these values. If not specified, pad_divisor_zyx must be provided. pad_divisor_zyx (tuple[int, int, int] | None): If set, pads each dimension to make it divisible by corresponding value in format (depth_div, height_div, width_div). If not specified, min_zyx must be provided. position (Literal["center", "random"]): Position where the volume is to be placed after padding. Default is 'center'. fill (tuple[float, ...] | float): Value to fill the border voxels for volume. Default: 0 fill_mask (tuple[float, ...] | float): Value to fill the border voxels for masks. Default: 0 p (float): Probability of applying the transform. Default: 1.0 Targets: volume, mask3d, keypoints Image types: uint8, float32 Note: Input volume should be a numpy array with dimensions ordered as (z, y, x) or (depth, height, width), with optional channel dimension as the last axis. Examples: >>> import numpy as np >>> import albumentations as A >>> >>> # Prepare sample data >>> volume = np.random.randint(0, 256, (10, 100, 100), dtype=np.uint8) # (D, H, W) >>> mask3d = np.random.randint(0, 2, (10, 100, 100), dtype=np.uint8) # (D, H, W) >>> keypoints = np.array([[20, 30, 5], [60, 70, 8]], dtype=np.float32) # (x, y, z) >>> keypoint_labels = [1, 2] # Labels for each keypoint >>> >>> # Create a transform with both min_zyx and pad_divisor_zyx >>> transform = A.Compose([ ... A.PadIfNeeded3D( ... min_zyx=(16, 128, 128), # Minimum size (depth, height, width) ... pad_divisor_zyx=(8, 16, 16), # Make dimensions divisible by these values ... position="center", # Center the volume in the padded space ... fill=0, # Fill value for volume ... fill_mask=1, # Fill value for mask ... p=1.0 ... ) ... ], keypoint_params=A.KeypointParams(format='xyz', label_fields=['keypoint_labels'])) >>> >>> # Apply the transform >>> transformed = transform( ... volume=volume, ... mask3d=mask3d, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # Get the transformed data >>> padded_volume = transformed["volume"] # Shape: (16, 128, 128) >>> padded_mask3d = transformed["mask3d"] # Shape: (16, 128, 128) >>> padded_keypoints = transformed["keypoints"] # Keypoints shifted by padding >>> padded_keypoint_labels = transformed["keypoint_labels"] # Labels remain unchanged cP\rSrSr%S\S'S\S'S\S'\"SS 9S S j5rS rg )PadIfNeeded3D.InitSchemai}zSAnnotated[tuple[int, int, int] | None, AfterValidator(check_range_bounds(0, None))]min_zyxzSAnnotated[tuple[int, int, int] | None, AfterValidator(check_range_bounds(1, None))]pad_divisor_zyxLiteral['center', 'random']positionaftermodecTURcURc Sn[U5eU$)zValidate that either min_zyx or pad_divisor_zyx is provided. Returns: Self: Self reference for method chaining Raises: ValueError: If both min_zyx and pad_divisor_zyx are None z6At least one of min_zyx or pad_divisor_zyx must be set)rrrn)r4msgs r-validate_params(PadIfNeeded3D.InitSchema.validate_paramss-||#(<(<(DN o%Kr,r$NrXr )r&r'r(r)r*r rr+r$r,r-r.r}s+ddll-- g &  ' r,r.cF>[TU]XEUS9 XlX lX0lgrw)r2r3rrr)r4rrrr"r#r1r5s r-r3PadIfNeeded3D.__init__s' d1= . r,c USRSSup4nX4U4n[U5VVs/sH[upx[R"UUR(aURUOSUR (aUR UOSS9PM] n nn[ R"U URURS9n SU 0$s snnf)a*Calculate padding parameters based on input data dimensions. Args: params (dict[str, Any]): Dictionary of existing parameters data (dict[str, Any]): Dictionary containing input data with volume, mask, etc. Returns: dict[str, Any]: Dictionary containing calculated padding parameters r:Nr) current_sizemin_sizedivisor)paddingsr py_randomr;) shape enumeraterMget_dimension_paddingrrr=adjust_padding_by_position3drr) r4r?r|depthheightwidthsizesrksizerr;s r-r*PadIfNeeded3D.get_params_dependent_on_datas $H~33BQ7u&%U+  ,  , ,!,0LLad373G3G,,Q/T  ,  22]]nn  7## sA"B;)rrr)NNcenterrrrT) rtuple[int, int, int] | Nonerrrrr"r!r#r!r1rUrrr_s@r-rr;s?BY)).047;08*+/0 !, !5 !. ! ( ! - !  ! !!$!$!$  !$!$r,rc<^\rSrSrSr\R \R\R4r "SS\ R5r S SU4Sjjjr SSjr SSjrSSjrSS jrSS jrSS jrS rU=r$)BaseCropAndPad3DiaNBase class for 3D transforms that need both cropping and padding. This class serves as a foundation for transforms that combine cropping and padding operations on 3D volumetric data. It provides functionality for calculating padding parameters, applying crop and pad operations to volumes, masks, and handling keypoint coordinate shifts. Args: pad_if_needed (bool): Whether to pad if the volume is smaller than target dimensions fill (tuple[float, ...] | float): Value to fill the padded voxels for volume fill_mask (tuple[float, ...] | float): Value to fill the padded voxels for mask pad_position (Literal["center", "random"]): How to distribute padding when needed "center" - equal amount on both sides, "random" - random distribution p (float): Probability of applying the transform. Default: 1.0 Targets: volume, mask3d, keypoints Note: This is a base class and not intended to be used directly. Use its derivatives like CenterCrop3D or RandomCrop3D instead, or create a custom transform by inheriting from this class. Examples: >>> import numpy as np >>> import albumentations as A >>> >>> # Example of a custom crop transform inheriting from BaseCropAndPad3D >>> class CustomFixedCrop3D(A.BaseCropAndPad3D): ... def __init__(self, crop_size: tuple[int, int, int] = (8, 64, 64), *args, **kwargs): ... super().__init__( ... pad_if_needed=True, ... fill=0, ... fill_mask=0, ... pad_position="center", ... *args, ... **kwargs ... ) ... self.crop_size = crop_size ... ... def get_params_dependent_on_data(self, params: dict[str, Any], data: dict[str, Any]) -> dict[str, Any]: ... # Get the volume shape ... volume = data["volume"] ... z, h, w = volume.shape[:3] ... target_z, target_h, target_w = self.crop_size ... ... # Check if padding is needed and calculate parameters ... pad_params = self._get_pad_params( ... image_shape=(z, h, w), ... target_shape=self.crop_size, ... ) ... ... # Update dimensions if padding is applied ... if pad_params is not None: ... z = z + pad_params["pad_front"] + pad_params["pad_back"] ... h = h + pad_params["pad_top"] + pad_params["pad_bottom"] ... w = w + pad_params["pad_left"] + pad_params["pad_right"] ... ... # Calculate fixed crop coordinates - always start at position (0,0,0) ... crop_coords = (0, target_z, 0, target_h, 0, target_w) ... ... return { ... "crop_coords": crop_coords, ... "pad_params": pad_params, ... } >>> >>> # Prepare sample data >>> volume = np.random.randint(0, 256, (10, 100, 100), dtype=np.uint8) # (D, H, W) >>> mask3d = np.random.randint(0, 2, (10, 100, 100), dtype=np.uint8) # (D, H, W) >>> keypoints = np.array([[20, 30, 5], [60, 70, 8]], dtype=np.float32) # (x, y, z) >>> keypoint_labels = [1, 2] # Labels for each keypoint >>> >>> # Use the custom transform in a pipeline >>> transform = A.Compose([ ... CustomFixedCrop3D( ... crop_size=(8, 64, 64), # Crop first 8x64x64 voxels (with padding if needed) ... p=1.0 ... ) ... ], keypoint_params=A.KeypointParams(format='xyz', label_fields=['keypoint_labels'])) >>> >>> # Apply the transform >>> transformed = transform( ... volume=volume, ... mask3d=mask3d, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # Get the transformed data >>> cropped_volume = transformed["volume"] # Shape: (8, 64, 64) >>> cropped_mask3d = transformed["mask3d"] # Shape: (8, 64, 64) >>> cropped_keypoints = transformed["keypoints"] # Keypoints shifted relative to crop >>> cropped_keypoint_labels = transformed["keypoint_labels"] # Labels remain unchanged c>\rSrSr%S\S'S\S'S\S'S\S'S rg ) BaseCropAndPad3D.InitSchemai&bool pad_if_neededr!r"r#r pad_positionr$Nr%r$r,r-r.r&s'',,11r,r.cP>[TU]US9 XlX lX0lX@lgr0)r2r3rr"r#r)r4rr"r#rr1r5s r-r3BaseCropAndPad3D.__init__,s+ 1* "(r,c`US:a#URRSU5nX- nX#4$S=p#X#4$)zGenerate random padding values. Args: pad (int): Total padding value to distribute Returns: tuple[int, int]: Random padding values (front, back) r)rrandintr4pad pad_startpad_ends r- _random_padBaseCropAndPad3D._random_pad:sF 7..q#6IoG!!#$ #I!!r,cUS-nX- nX#4$)zGenerate centered padding values. Args: pad (int): Total padding value to distribute Returns: tuple[int, int]: Centered padding values (front, back) rIr$rs r- _center_padBaseCropAndPad3D._center_padKs1H /!!r,cUR(dgUup4nUupgn[SXc- 5n [SXt- 5n [SX- 5n U S:Xa U S:XaU S:XagURS:Xa;URU 5upURU 5upURU 5unnO:UR U 5upUR U 5upUR U 5unnU U UUUUS.$)a+Calculate padding parameters to reach target shape. Args: image_shape (tuple[int, int, int]): Current shape (depth, height, width) target_shape (tuple[int, int, int]): Target shape (depth, height, width) Returns: dict[str, int] | None: Padding parameters or None if no padding needed Nrr) pad_frontpad_backpad_top pad_bottompad_left pad_right)rmaxrrr)r4 image_shape target_shapezhwtarget_ztarget_htarget_wz_padh_padw_padz_frontz_backh_toph_bottomw_leftw_rights r-_get_pad_params BaseCropAndPad3D._get_pad_paramsYs!!a'3$HAx|$Ax|$Ax|$ A:%1*!    ("..u5OG"..u5OE"..u5OFG#..u5OG"..u5OE"..u5OFG!"   r,c [R"X5nUb:USUSUSUSUSUS4n[R"UUURS9$U$)aApply cropping and padding to a 3D volume. Args: volume (np.ndarray): Input volume with shape (depth, height, width) or (depth, height, width, channels) crop_coords (tuple[int, int, int, int, int, int]): Crop coordinates (z1, z2, y1, y2, x1, x2) pad_params (dict[str, int] | None): Padding parameters or None if no padding needed **params (Any): Additional parameters Returns: np.ndarray: Cropped and padded volume with same number of dimensions as input rrrrrrr;r<)r=crop3dr>r")r4r: crop_coords pad_paramsr?croppedr;s r-r@ BaseCropAndPad3D.apply_to_volumesz(**V1  !;':&9%<(:&;' G))ii  r,c [R"X5nUbDUSUSUSUSUSUS4n[R"UU[SUR5S9$U$) aApply cropping and padding to a 3D mask. Args: mask3d (np.ndarray): Input mask with shape (depth, height, width) or (depth, height, width, channels) crop_coords (tuple[int, int, int, int, int, int]): Crop coordinates (z1, z2, y1, y2, x1, x2) pad_params (dict[str, int] | None): Padding parameters or None if no padding needed **params (Any): Additional parameters Returns: np.ndarray: Cropped and padded mask with same number of dimensions as input rrrrrrrCr)r=rr>rr#)r4rDrrr?rr;s r-rE BaseCropAndPad3D.apply_to_mask3ds(**V1  !;':&9%<(:&;' G))>> import numpy as np >>> import albumentations as A >>> >>> # Prepare sample data >>> volume = np.random.randint(0, 256, (20, 200, 200), dtype=np.uint8) # (D, H, W) >>> mask3d = np.random.randint(0, 2, (20, 200, 200), dtype=np.uint8) # (D, H, W) >>> keypoints = np.array([[100, 100, 10], [150, 150, 15]], dtype=np.float32) # (x, y, z) >>> keypoint_labels = [1, 2] # Labels for each keypoint >>> >>> # Create the transform - crop to 16x128x128 from center >>> transform = A.Compose([ ... A.CenterCrop3D( ... size=(16, 128, 128), # Output size (depth, height, width) ... pad_if_needed=True, # Pad if input is smaller than crop size ... fill=0, # Fill value for volume padding ... fill_mask=1, # Fill value for mask padding ... p=1.0 ... ) ... ], keypoint_params=A.KeypointParams(format='xyz', label_fields=['keypoint_labels'])) >>> >>> # Apply the transform >>> transformed = transform( ... volume=volume, ... mask3d=mask3d, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # Get the transformed data >>> cropped_volume = transformed["volume"] # Shape: (16, 128, 128) >>> cropped_mask3d = transformed["mask3d"] # Shape: (16, 128, 128) >>> cropped_keypoints = transformed["keypoints"] # Keypoints shifted relative to center crop >>> cropped_keypoint_labels = transformed["keypoint_labels"] # Labels remain unchanged >>> >>> # Example with a small volume that requires padding >>> small_volume = np.random.randint(0, 256, (10, 100, 100), dtype=np.uint8) >>> small_transform = A.Compose([ ... A.CenterCrop3D( ... size=(16, 128, 128), ... pad_if_needed=True, # Will pad since the input is smaller ... fill=0, ... p=1.0 ... ) ... ]) >>> small_result = small_transform(volume=small_volume) >>> padded_and_cropped = small_result["volume"] # Shape: (16, 128, 128), padded to size c>\rSrSr%S\S'S\S'S\S'S\S'S rg ) CenterCrop3D.InitSchemaiOLAnnotated[tuple[int, int, int], AfterValidator(check_range_bounds(1, None))]rrrr!r"r#r$Nr%r$r,r-r.rOZZ'',,r,r.c4>[TU]UUUSUS9 Xlg)Nrrr"r#rr1r2r3rr4rrr"r#r1r5s r-r3CenterCrop3D.__init__U- '!   r,c USnURSSupEnURupxn URXEU4URS9n U b'XJS-U S-nXZS-U S-nXjS -U S -nXG:d XX:dXi:a$S URS US US US3 n [U 5eXG- S-n XX- S-n Xi- S-nU X-U X-UX-4nUU S.$)a0Calculate crop coordinates for center cropping. Args: params (dict[str, Any]): Dictionary of existing parameters data (dict[str, Any]): Dictionary containing input data with volume, mask, etc. Returns: dict[str, Any]: Dictionary containing crop coordinates and optional padding parameters r:Nrrrrrrrrrz Crop size z# is larger than padded image size (z, z8). This should not happen - please report this as a bug.rIrr)rrrrn)r4r?r|r:rrrrrrrrz_starth_startw_startrs r-r)CenterCrop3D.get_params_dependent_on_datafsLh,,r"a'+yy$H))q *  !{++j.DDAy))J|,DDAz**Z -DDA <1<1<TYYK'J1#RPQsRTUVTWXHI S/ !>> import numpy as np >>> import albumentations as A >>> >>> # Prepare sample data >>> volume = np.random.randint(0, 256, (20, 200, 200), dtype=np.uint8) # (D, H, W) >>> mask3d = np.random.randint(0, 2, (20, 200, 200), dtype=np.uint8) # (D, H, W) >>> keypoints = np.array([[100, 100, 10], [150, 150, 15]], dtype=np.float32) # (x, y, z) >>> keypoint_labels = [1, 2] # Labels for each keypoint >>> >>> # Create the transform with random crop and padding if needed >>> transform = A.Compose([ ... A.RandomCrop3D( ... size=(16, 128, 128), # Output size (depth, height, width) ... pad_if_needed=True, # Pad if input is smaller than crop size ... fill=0, # Fill value for volume padding ... fill_mask=1, # Fill value for mask padding ... p=1.0 ... ) ... ], keypoint_params=A.KeypointParams(format='xyz', label_fields=['keypoint_labels'])) >>> >>> # Apply the transform >>> transformed = transform( ... volume=volume, ... mask3d=mask3d, ... keypoints=keypoints, ... keypoint_labels=keypoint_labels ... ) >>> >>> # Get the transformed data >>> cropped_volume = transformed["volume"] # Shape: (16, 128, 128) >>> cropped_mask3d = transformed["mask3d"] # Shape: (16, 128, 128) >>> cropped_keypoints = transformed["keypoints"] # Keypoints shifted relative to random crop >>> cropped_keypoint_labels = transformed["keypoint_labels"] # Labels remain unchanged c>\rSrSr%S\S'S\S'S\S'S\S'S rg ) RandomCrop3D.InitSchemairrrrr!r"r#r$Nr%r$r,r-r.rrr,r.c4>[TU]UUUSUS9 Xlg)Nrandomrrrs r-r3RandomCrop3D.__init__rr,cUSnURSSupEnURupxn URXEU4URS9n U b'XJS-U S-nXZS-U S-nXjS -U S -nURR S [ S XG- 55n URR S [ S XX- 55n URR S [ S Xi- 55n U X-U X-U X-4nUU S .$) a6Calculate random crop coordinates. Args: params (dict[str, Any]): Dictionary of existing parameters data (dict[str, Any]): Dictionary containing input data with volume, mask, etc. Returns: dict[str, Any]: Dictionary containing randomly generated crop coordinates and optional padding parameters r:Nrrrrrrrrrr)rrrrrr)r4r?r|r:rrrrrrrrrrrs r-r)RandomCrop3D.get_params_dependent_on_datas6h,,r"a'+yy$H))q *  !{++j.DDAy))J|,DDAz**Z -DDA..((C1<,@A..((C1<,@A..((C1<,@A           '$  r,rrrrrr_s@r-rrs7r-,-$*+/0 "(  -   "0 0 0   0 0 r,rc&^\rSrSrSr\R \R\R4r "SS\ R5r S S U4Sjjjr SSjr SSjrSSjrSS jrSS jrS rU=r$)ri%a3 CoarseDropout3D randomly drops out cuboid regions from a 3D volume and optionally, the corresponding regions in an associated 3D mask, to simulate occlusion and varied object sizes found in real-world volumetric data. Args: num_holes_range (tuple[int, int]): Range (min, max) for the number of cuboid regions to drop out. Default: (1, 1) hole_depth_range (tuple[float, float]): Range (min, max) for the depth of dropout regions as a fraction of the volume depth (between 0 and 1). Default: (0.1, 0.2) hole_height_range (tuple[float, float]): Range (min, max) for the height of dropout regions as a fraction of the volume height (between 0 and 1). Default: (0.1, 0.2) hole_width_range (tuple[float, float]): Range (min, max) for the width of dropout regions as a fraction of the volume width (between 0 and 1). Default: (0.1, 0.2) fill (tuple[float, float] | float): Value for the dropped voxels. Can be: - int or float: all channels are filled with this value - tuple: tuple of values for each channel Default: 0 fill_mask (tuple[float, float] | float | None): Fill value for dropout regions in the 3D mask. If None, mask regions corresponding to volume dropouts are unchanged. Default: None p (float): Probability of applying the transform. Default: 0.5 Targets: volume, mask3d, keypoints Image types: uint8, float32 Note: - The actual number and size of dropout regions are randomly chosen within the specified ranges. - All values in hole_depth_range, hole_height_range and hole_width_range must be between 0 and 1. - If you want to apply dropout only in the XY plane while preserving the full depth dimension, consider using CoarseDropout instead. CoarseDropout will apply the same rectangular dropout to each slice independently, effectively creating cylindrical dropout regions that extend through the entire depth of the volume. Examples: >>> import numpy as np >>> import albumentations as A >>> volume = np.random.randint(0, 256, (10, 100, 100), dtype=np.uint8) # (D, H, W) >>> mask3d = np.random.randint(0, 2, (10, 100, 100), dtype=np.uint8) # (D, H, W) >>> aug = A.CoarseDropout3D( ... num_holes_range=(3, 6), ... hole_depth_range=(0.1, 0.2), ... hole_height_range=(0.1, 0.2), ... hole_width_range=(0.1, 0.2), ... fill=0, ... p=1.0 ... ) >>> transformed = aug(volume=volume, mask3d=mask3d) >>> transformed_volume, transformed_mask3d = transformed["volume"], transformed["mask3d"] c\rSrSr%S\S'S\S'S\S'S\S'S\S 'S \S '\SS j5r\"S S9SSj5rSr g)CoarseDropout3D.InitSchemai]zfAnnotated[tuple[int, int], AfterValidator(check_range_bounds(0, None)), AfterValidator(nondecreasing)]num_holes_rangezgAnnotated[tuple[float, float], AfterValidator(check_range_bounds(0, 1)), AfterValidator(nondecreasing)]hole_depth_rangehole_height_rangehole_width_ranger!r" tuple[float, ...] | float | Noner#c^SUSs=::aUSs=::aS::dO [SUSU35eg)aValidate that range values are between 0 and 1 and in non-decreasing order. Args: range_value (tuple[float, float]): Tuple of (min, max) values to check range_name (str): Name of the range for error reporting Raises: ValueError: If range values are invalid rzAll values in z_ should be in [0, 1] range and first value should be less or equal than the second value. Got: N)rn) range_value range_names r-validate_range)CoarseDropout3D.InitSchema.validate_rangeusH A=+a.=A= $ZL1KKV-Y>r,rrcURURS5 URURS5 URURS5 U$)Nr rr)rr rr)r4s r- _check_ranges(CoarseDropout3D.InitSchema._check_rangessL    5 57I J    6 68K L    5 57I JKr,r$N)rtuple[float, float]rstrrXNoner) r&r'r(r)r* staticmethodrr rr+r$r,r-r.r ]sc        ('33    " g &  ' r,r.ch>[TU]US9 XlX lX0lX@lXPlX`lgr0)r2r3r r rrr"r#) r4r r rrr"r#r1r5s r-r3CoarseDropout3D.__init__s7 1. 0!2 0 "r,c 6USSupgn[R"S[R"X`RR"USU06-55R [ 5n [R"S[R"XpRR"USU06-55R [ 5n [R"S[R"XRR"USU06-55R [ 5n XU 4$)a(Calculate dimensions for dropout holes. Args: volume_shape (tuple[int, int, int]): Shape of the volume (depth, height, width) depth_range (tuple[float, float]): Range for hole depth as fraction of volume depth height_range (tuple[float, float]): Range for hole height as fraction of volume height width_range (tuple[float, float]): Range for hole width as fraction of volume width size (int): Number of holes to generate Returns: tuple[np.ndarray, np.ndarray, np.ndarray]: Arrays of hole dimensions (depths, heights, widths) Nrrr)rKmaximumceilrandom_generatoruniformastyperi) r4 volume_shape depth_range height_range width_rangerrrr hole_depths hole_heights hole_widthss r-calculate_hole_dimensions)CoarseDropout3D.calculate_hole_dimensionss* ,BQ/ujjBGGE4I4I4Q4QS^4jei4j,j$klsstwx zz!RWWV6K6K6S6SUa6mhl6m-m%novv  jjBGGE4I4I4Q4QS^4jei4j,j$klsstwx +55r,cUSRSSnURR"UR6nUR UUR UR URUS9upVnUSSupn URRSX- S-US9n URRSX- S-US9n URRSX- S-US9n X-nX-nX-n[R"XXUU/SS9nS U0$) a1Generate parameters for coarse dropout based on input data. Args: params (dict[str, Any]): Dictionary of existing parameters data (dict[str, Any]): Dictionary containing input data with volume, mask, etc. Returns: dict[str, Any]: Dictionary containing generated hole parameters for dropout r:Nrrrr)axisholes) rrrr r-r rrr#integersrKstack)r4r?r|r& num_holesr*r+r,rrrz_miny_minx_minz_maxy_maxx_maxr2s r-r,CoarseDropout3D.get_params_dependent_on_datas1H~++BQ/ NN**D,@,@A 151O1O   ! !  " "  ! ! 2P2 . ; ,BQ/u%%..q%2E2IPY.Z%%..q&2G!2KR[.\%%..q%2E2IPY.Z#$#%eUC"Mr,c hURS:XaU$[R"XUR5$)aApply dropout to a 3D volume. Args: volume (np.ndarray): Input volume with shape (depth, height, width) or (depth, height, width, channels) holes (np.ndarray): Array of holes with shape (num_holes, 6). Each hole is represented as [z1, y1, x1, z2, y2, x2] **params (Any): Additional parameters Returns: np.ndarray: Volume with holes filled with the given value r)rr=cutout3dr")r4r:r2r?s r-r@CoarseDropout3D.apply_to_volumes) ::?M||F49955r,c URbURS:XaU$[R"XUR5$)a{Apply dropout to a 3D mask. Args: mask (np.ndarray): Input mask with shape (depth, height, width) or (depth, height, width, channels) holes (np.ndarray): Array of holes with shape (num_holes, 6). Each hole is represented as [z1, y1, x1, z2, y2, x2] **params (Any): Additional parameters Returns: np.ndarray: Mask with holes filled with the given value r)r#rr=r>)r4maskr2r?s r- apply_to_maskCoarseDropout3D.apply_to_masks2 >> !UZZ1_K||D88r,c URS:XaU$[SURS55nUbURR(dU$[ R "X5$)aApply dropout to keypoints. Args: keypoints (np.ndarray): Array of keypoints with shape (num_keypoints, 3+). The first three columns are x, y, z coordinates. holes (np.ndarray): Array of holes with shape (num_holes, 6). Each hole is represented as [z1, y1, x1, z2, y2, x2] **params (Any): Additional parameters Returns: np.ndarray: Filtered keypoints with same shape as input rrrO)rr get_processorr?remove_invisibler=filter_keypoints_in_holes3d)r4rOr2r? processors r-rQ"CoarseDropout3D.apply_to_keypointssX& ::? -t/A/A+/NO  I$4$4$E$E ..y@@r,)r"r#r rrr ))rrg?g?rJrJrNg?)r rr rrrrrr"r!r#rr1rU) r&rr'rr(rr)rrrirXz)tuple[np.ndarray, np.ndarray, np.ndarray]r)r:rVr2rVr?rrXrV)rArVr2rVr?rrXrV)rOrVr2rVr?rrXrV)r&r'r(r)rYrrZr[r\r]rr.r3r-rr@rBrQr+r^r_s@r-rr%s"3j0A0ABH/[++/f,20:1;0:*+6:#(#.#/ # . # ( #4# ##$6*6)6* 6 ) 6  6 36>" H6$9$AAA A  AAr,rc^\rSrSrSr\R \R\R4r SS U4Sjjjr S Sjr S Sjr S Sjr SrU=r$) ri#atApplies a random cubic symmetry transformation to a 3D volume. This transform is a 3D extension of D4. While D4 handles the 8 symmetries of a square (4 rotations x 2 reflections), CubicSymmetry handles all 48 symmetries of a cube. Like D4, this transform does not create any interpolation artifacts as it only remaps voxels from one position to another without any interpolation. The 48 transformations consist of: - 24 rotations (orientation-preserving): * 4 rotations around each face diagonal (6 face diagonals x 4 rotations = 24) - 24 rotoreflections (orientation-reversing): * Reflection through a plane followed by any of the 24 rotations For a cube, these transformations preserve: - All face centers (6) - All vertex positions (8) - All edge centers (12) works with 3D volumes and masks of the shape (D, H, W) or (D, H, W, C) Args: p (float): Probability of applying the transform. Default: 1.0 Targets: volume, mask3d, keypoints Image types: uint8, float32 Note: - This transform is particularly useful for data augmentation in 3D medical imaging, crystallography, and voxel-based 3D modeling where the object's orientation is arbitrary. - All transformations preserve the object's chirality (handedness) when using pure rotations (indices 0-23) and invert it when using rotoreflections (indices 24-47). Examples: >>> import numpy as np >>> import albumentations as A >>> volume = np.random.randint(0, 256, (10, 100, 100), dtype=np.uint8) # (D, H, W) >>> mask3d = np.random.randint(0, 2, (10, 100, 100), dtype=np.uint8) # (D, H, W) >>> transform = A.CubicSymmetry(p=1.0) >>> transformed = transform(volume=volume, mask3d=mask3d) >>> transformed_volume = transformed["volume"] >>> transformed_mask3d = transformed["mask3d"] See Also: - D4: The 2D version that handles the 8 symmetries of a square c >[TU]US9 gr0)r2r3)r4r1r5s r-r3CubicSymmetry.__init__Zs 1r,c^USRnURRSS5US.$)a1Generate parameters for cubic symmetry transformation. Args: params (dict[str, Any]): Dictionary of existing parameters data (dict[str, Any]): Dictionary containing input data with volume, mask, etc. Returns: dict[str, Any]: Dictionary containing the randomly selected transformation index r:r/)indexr&)rrr)r4r?r|r&s r-r*CubicSymmetry.get_params_dependent_on_data`s/ H~++ //26 UUr,c .[R"X5$)aUApply cubic symmetry transformation to a 3D volume. Args: volume (np.ndarray): Input volume with shape (depth, height, width) or (depth, height, width, channels) index (int): Index of the transformation to apply (0-47) **params (Any): Additional parameters Returns: np.ndarray: Transformed volume with same shape as input )r=transform_cube)r4r:rPr?s r-r@CubicSymmetry.apply_to_volumess!!&00r,c 2[R"XUSS9$)aApply cubic symmetry transformation to keypoints. Args: keypoints (np.ndarray): Array of keypoints with shape (num_keypoints, 3+). The first three columns are x, y, z coordinates. index (int): Index of the transformation to apply (0-47) **params (Any): Additional parameters Returns: np.ndarray: Transformed keypoints with same shape as input r&)r&)r=transform_cube_keypoints)r4rOrPr?s r-rQ CubicSymmetry.apply_to_keypointss++I6R`Kabbr,r$r)r1rUr)r:rVrPrir?rrXrV)rOrVrPrir?rrXrV)r&r'r(r)rYrrZr[r\r]r3rr@rQr+r^r_s@r-rr#sr2h0A0ABH  VVV  V& 1 c cr,r)*rY __future__rtypingrrrrrnumpyrKpydanticr r r typing_extensionsr &albumentations.augmentations.geometricr rM)albumentations.augmentations.transforms3dr=#albumentations.core.keypoints_utilsralbumentations.core.pydanticrr(albumentations.core.transforms_interfacerr$albumentations.core.type_definitionsr__all__r{rrrrrrrrr$r,r-rds#77EE"KGBJY8 h[C [C||$I|$~F$IF$RA<{A