hR SrSSKJr SSKrSSKrSSKrSSKJr SSKJ r J r J r J r J r SSKrSSKrSSKrSSKJrJrJrJrJrJrJrJrJr SSKJrJrJrJrJ r J!r!J"r" SSK#J$r$ SS K%J&r&J'r' SSK(J)s J*s J+r, SS K-J+r. SS K/J0r0 SS K1J+r2 SS K3J4r4J5r5 SS K6J7r7J8r8J9r9J:r:J;r;JJ?r?J@r@ SSKAJBrBJCrCJDrDJErE SSKFJGrG /SQrHSrISrJ"SS\@5rK"SS\@5rL"SS\@5rM"SS\@5rN"SS\@5rO"SS\@5rP"S S!\@5rQ"S"S#\@5rR"S$S%\@5rS"S&S'\@5rT"S(S)\@5rU"S*S+\@5rV"S,S-\@5rW"S.S/\@5rX"S0S1\@5rY"S2S3\@5rZ"S4S5\@5r["S6S7\@5r\"S8S9\@5r]"S:S;\@5r^"S<S=\@5r_"S>S?\@5r`"S@SA\@5ra"SBSC\5rb"SDSE\@5rc"SFSG\@5rd"SHSI\@5re"SJSK\@5rf"SLSM\@5rg"SNSO\@5rh"SPSQ\@5ri"SRSS\@5rj"STSU\@5rk"SVSW\@5rl"SXSY\@5rm\n"/\2RSZR5Q\2RS[R5Q76\q"\2RSZR55\q"\2RS[R55S\S]S^.rr"S_S`\@5rs"SaSb\@5rt"ScSd\5ru"SeSf\u5rv"SgSh\u5rw"SiSj\u5rx"SkSl\u5ry\ \ \v\w\x\y4\"SmSn94rz"SoSp\@5r{"SqSr\{5r|"SsSt\@5r}"SuSv\@5r~"SwSx\@5r"SySz\@5r"S{S|\@5r"S}S~\@5rg)a(Pixel-level transformations for image augmentation. This module contains transforms that modify pixel values without changing the geometry of the image. Includes transforms for adjusting color, brightness, contrast, adding noise, simulating weather effects, and other pixel-level manipulations. ) annotationsN)Sequence) AnnotatedAnyCallableUnioncast) MAX_VALUES_BY_DTYPENUM_MULTI_CHANNEL_DIMENSIONSbatch_transformget_num_channelsis_grayscale_image is_rgb_imagemultiply normalizenormalize_per_image)AfterValidator BaseModel ConfigDictFieldValidationInfofield_validatormodel_validator)special)LiteralSelf) functional)BlurInitSchema) check_range non_rgb_error)NonNegativeFloatRangeTypeOnePlusFloatRangeTypeOnePlusIntRangeTypeSymmetricRangeTypeZeroOneRangeTypecheck_range_bounds nondecreasing)BaseTransformInitSchemaImageOnlyTransform)MAX_RAIN_ANGLENUM_RGB_CHANNELSPAIRSEVEN)to_tuple),CLAHE AdditiveNoise AutoContrastChannelShuffleChromaticAberration ColorJitter DownscaleEmbossEqualizeFancyPCA GaussNoiseHEStainHueSaturationValueISONoise IlluminationImageCompression InvertImgMultiplicativeNoise NormalizePlanckianJitterPlasmaBrightnessContrast PlasmaShadow PosterizeRGBShiftRandomBrightnessContrast RandomFog RandomGamma RandomGravel RandomRain RandomShadow RandomSnowRandomSunFlareRandomToneCurveRingingOvershoot SaltAndPepperSharpen ShotNoiseSolarizeSpatter SuperpixelsToGrayToRGBToSepia UnsharpMaskc^\rSrSrSr"SS\5rSSU4SjjjrSSjr\ "SSS S 9SS j5r \ "SS SS 9SS j5r \ "SSSS 9SS j5r Sr U=r$)rAwa Applies various normalization techniques to an image. The specific normalization technique can be selected with the `normalization` parameter. Standard normalization is applied using the formula: `img = (img - mean * max_pixel_value) / (std * max_pixel_value)`. Other normalization techniques adjust the image based on global or per-channel statistics, or scale pixel values to a specified range. Args: mean (tuple[float, float] | float | None): Mean values for standard normalization. For "standard" normalization, the default values are ImageNet mean values: (0.485, 0.456, 0.406). std (tuple[float, float] | float | None): Standard deviation values for standard normalization. For "standard" normalization, the default values are ImageNet standard deviation :(0.229, 0.224, 0.225). max_pixel_value (float | None): Maximum possible pixel value, used for scaling in standard normalization. Defaults to 255.0. normalization (Literal["standard", "image", "image_per_channel", "min_max", "min_max_per_channel"]): Specifies the normalization technique to apply. Defaults to "standard". - "standard": Applies the formula `(img - mean * max_pixel_value) / (std * max_pixel_value)`. The default mean and std are based on ImageNet. You can use mean and std values of (0.5, 0.5, 0.5) for inception normalization. And mean values of (0, 0, 0) and std values of (1, 1, 1) for YOLO. - "image": Normalizes the whole image based on its global mean and standard deviation. - "image_per_channel": Normalizes the image per channel based on each channel's mean and standard deviation. - "min_max": Scales the image pixel values to a [0, 1] range based on the global minimum and maximum pixel values. - "min_max_per_channel": Scales each channel of the image pixel values to a [0, 1] range based on the per-channel minimum and maximum pixel values. p (float): Probability of applying the transform. Defaults to 1.0. Targets: image Image types: uint8, float32 Note: - For "standard" normalization, `mean`, `std`, and `max_pixel_value` must be provided. - For other normalization types, these parameters are ignored. - For inception normalization, use mean values of (0.5, 0.5, 0.5). - For YOLO normalization, use mean values of (0, 0, 0) and std values of (1, 1, 1). - This transform is often used as a final step in image preprocessing pipelines to prepare images for neural network input. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> # Standard ImageNet normalization >>> transform = A.Normalize( ... mean=(0.485, 0.456, 0.406), ... std=(0.229, 0.224, 0.225), ... max_pixel_value=255.0, ... p=1.0 ... ) >>> normalized_image = transform(image=image)["image"] >>> >>> # Min-max normalization >>> transform_minmax = A.Normalize(normalization="min_max", p=1.0) >>> normalized_image_minmax = transform_minmax(image=image)["image"] References: - ImageNet mean and std: https://pytorch.org/vision/stable/models.html - Inception preprocessing: https://keras.io/api/applications/inceptionv3/ cZ\rSrSr%S\S'S\S'S\S'S\S'\"S S 9SS j5rS rg )Normalize.InitSchema tuple[float, ...] | float | Nonemeanstd float | Nonemax_pixel_valueSLiteral['standard', 'image', 'image_per_channel', 'min_max', 'min_max_per_channel'] normalizationaftermodecURb*URbURcURS:Xa [ S5eU$)NstandardzKmean, std, and max_pixel_value must be provided for standard normalization.)rcrdrfrh ValueErrorselfs g/var/www/fran/franai/venv/lib/python3.13/site-packages/albumentations/augmentations/pixel/transforms.py_validate_normalization,Normalize.InitSchema._validate_normalizationsH !88#((0T5G5G:5U aKNreturnr)__name__ __module__ __qualname____firstlineno____annotations__rrr__static_attributes__rurtrq InitSchemar`s7.. --%%   g &  ' rtr~c$>[TU]US9 Xl[R"U[R S9U-UlX l[R"[R"U[R S9U-5Ul X0l X@l g)Npdtype) super__init__rcnparrayfloat32mean_nprd reciprocal denominatorrfrh)rprcrdrfrhr __class__s rqrNormalize.__init__sp 1 xxBJJ7/I == HHS +o =  /*rtc URS:Xa![UURUR5$[ XR5$)zApply normalization to the input image. Args: img (np.ndarray): The input image to normalize. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The normalized image. rm)rhrrrrrpimgparamss rqapplyNormalize.applysE    +     #3(:(:;;rtchannelTF has_batch_dim has_depth_dimc (UR"U40UD6$)zApply normalization to a batch of images. Args: images (np.ndarray): Batch of images to normalize with shape (batch, height, width, channels). **params (Any): Additional parameters. Returns: np.ndarray: Normalized batch of images. rrpimagesrs rqapply_to_imagesNormalize.apply_to_imageszz&+F++rtc (UR"U40UD6$)zApply normalization to a 3D volume. Args: volume (np.ndarray): 3D volume to normalize with shape (depth, height, width, channels). **params (Any): Additional parameters. Returns: np.ndarray: Normalized 3D volume. rrpvolumers rqapply_to_volumeNormalize.apply_to_volume rrtc (UR"U40UD6$)a Apply normalization to a batch of 3D volumes. Args: volumes (np.ndarray): Batch of 3D volumes to normalize with shape (batch, depth, height, width, channels). **params (Any): Additional parameters. Returns: np.ndarray: Normalized batch of 3D volumes. rrpvolumesrs rqapply_to_volumesNormalize.apply_to_volumesszz',V,,rt)rrfrcrrhrd))g ףp= ?gv/?gCl?)gZd;O?gy&1?g?o@rm?) rcrbrdrbrfrerhrgrfloatr np.ndarrayrrrwrrrrrrwrrrrrrwrrrrrrwrrxryrzr{__doc__r(r~rrr rrrr} __classcell__rs@rqrArAws@D,42G0E(- +.+.+& +  + ++0<&Yd%H ,I ,Ye4H ,I ,Yd$G -H -rtrAc^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) r>i(aDecrease image quality by applying JPEG or WebP compression. This transform simulates the effect of saving an image with lower quality settings, which can introduce compression artifacts. It's useful for data augmentation and for testing model robustness against varying image qualities. Args: quality_range (tuple[int, int]): Range for the compression quality. The values should be in [1, 100] range, where: - 1 is the lowest quality (maximum compression) - 100 is the highest quality (minimum compression) Default: (99, 100) compression_type (Literal["jpeg", "webp"]): Type of compression to apply. - "jpeg": JPEG compression - "webp": WebP compression Default: "jpeg" p (float): Probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 Number of channels: Any Note: - This transform expects images with 1, 3, or 4 channels. - For JPEG compression, alpha channels (4th channel) will be ignored. - WebP compression supports transparency (4 channels). - The actual file is not saved to disk; the compression is simulated in memory. - Lower quality values result in smaller file sizes but may introduce visible artifacts. - This transform can be useful for: * Data augmentation to improve model robustness * Testing how models perform on images of varying quality * Simulating images transmitted over low-bandwidth connections Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> transform = A.ImageCompression(quality_range=(50, 90), compression_type=0, p=1.0) >>> result = transform(image=image) >>> compressed_image = result["image"] References: - JPEG compression: https://en.wikipedia.org/wiki/JPEG - WebP compression: https://developers.google.com/speed/webp c*\rSrSr%S\S'S\S'Srg)ImageCompression.InitSchemai_zeAnnotated[tuple[int, int], AfterValidator(check_range_bounds(1, 100)), AfterValidator(nondecreasing)] quality_rangeLiteral['jpeg', 'webp']compression_typeruNrxryrzr{r|r}rurtrqr~r_s  21rtr~c8>[TU]US9 X lXlgNr)rrrr)rprrrrs rqrImageCompression.__init__hs! 1* 0rtc 0[R"XU5$)amApply compression to the input image. Args: img (np.ndarray): The input image to be compressed. quality (int): Compression quality level (1-100). image_type (Literal[".jpg", ".webp"]): File extension indicating compression format. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The compressed image. )fpixelimage_compression)rprquality image_typers rqrImageCompression.applyrs&''jAArtcvURS:XaSOSnURR"UR6US.$)aGenerate random parameters for the transform. Returns: dict[str, int | str]: Dictionary with the following keys: - "quality" (int): Random quality value within the specified range. - "image_type" (str): File extension for the chosen compression type. jpegz.jpgz.webp)rr)r py_randomrandintr)rprs rq get_paramsImageCompression.get_paramss? $44>VG ~~--t/A/AB$  rt)rr)r)cd?)rrrtuple[int, int]rr) rrrintrzLiteral['.jpg', '.webp']rrrwr)rwzdict[str, int | str] rxryrzr{rr(r~rrrr}rrs@rqr>r>(s4l2,25;)2 111'1  11B BB- B  B  B*  rtr>c^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) rMiu Applies a random snow effect to the input image. This transform simulates snowfall by either bleaching out some pixel values or adding a snow texture to the image, depending on the chosen method. Args: snow_point_range (tuple[float, float]): Range for the snow point threshold. Both values should be in the (0, 1) range. Default: (0.1, 0.3). brightness_coeff (float): Coefficient applied to increase the brightness of pixels below the snow_point threshold. Larger values lead to more pronounced snow effects. Should be > 0. Default: 2.5. method (Literal["bleach", "texture"]): The snow simulation method to use. Options are: - "bleach": Uses a simple pixel value thresholding technique. - "texture": Applies a more realistic snow texture overlay. Default: "texture". p (float): Probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 Note: - The "bleach" method increases the brightness of pixels above a certain threshold, creating a simple snow effect. This method is faster but may look less realistic. - The "texture" method creates a more realistic snow effect through the following steps: 1. Converts the image to HSV color space for better control over brightness. 2. Increases overall image brightness to simulate the reflective nature of snow. 3. Generates a snow texture using Gaussian noise, which is then smoothed with a Gaussian filter. 4. Applies a depth effect to the snow texture, making it more prominent at the top of the image. 5. Blends the snow texture with the original image using alpha compositing. 6. Adds a slight blue tint to simulate the cool color of snow. 7. Adds random sparkle effects to simulate light reflecting off snow crystals. This method produces a more realistic result but is computationally more expensive. Mathematical Formulation: For the "bleach" method: Let L be the lightness channel in HLS color space. For each pixel (i, j): If L[i, j] > snow_point: L[i, j] = L[i, j] * brightness_coeff For the "texture" method: 1. Brightness adjustment: V_new = V * (1 + brightness_coeff * snow_point) 2. Snow texture generation: T = GaussianFilter(GaussianNoise(μ=0.5, sigma=0.3)) 3. Depth effect: D = LinearGradient(1.0 to 0.2) 4. Final pixel value: P = (1 - alpha) * original_pixel + alpha * (T * D * 255) where alpha is the snow intensity factor derived from snow_point. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) # Default usage (bleach method) >>> transform = A.RandomSnow(p=1.0) >>> snowy_image = transform(image=image)["image"] # Using texture method with custom parameters >>> transform = A.RandomSnow( ... snow_point_range=(0.2, 0.4), ... brightness_coeff=2.0, ... method="texture", ... p=1.0 ... ) >>> snowy_image = transform(image=image)["image"] References: - Bleach method: https://github.com/UjjwalSaxena/Automold--Road-Augmentation-Library - Texture method: Inspired by computer graphics techniques for snow rendering and atmospheric scattering simulations. c@\rSrSr%S\S'\"SS9rS\S'S\S 'S rg ) RandomSnow.InitSchemaigAnnotated[tuple[float, float], AfterValidator(check_range_bounds(0, 1)), AfterValidator(nondecreasing)]snow_point_rangergtrbrightness_coeffLiteral['bleach', 'texture']methodruN)rxryrzr{r|rrr}rurtrqr~rs#  #(1+%-,,rtr~cD>[TU]US9 X lXlX0lgr)rrrrr)rprrrrrs rqrRandomSnow.__init__s& 1 0 0 rtc [U5 URS:Xa![R"XUR5$URS:Xa$[R "UUURUU5$[ SUR35e)aApply the snow effect to the input image. Args: img (np.ndarray): The input image to apply the snow effect to. snow_point (float): The snow point threshold. snow_texture (np.ndarray): The snow texture overlay. sparkle_mask (np.ndarray): The sparkle mask for the snow effect. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied snow effect. bleachtexturezUnknown snow method: )r rradd_snow_bleachradd_snow_texturern)rpr snow_point snow_texture sparkle_maskrs rqrRandomSnow.applys~* c ;;( "))#4;P;PQ Q ;;) #**%%  0 >??rtcUSSSnURR"UR6SSS.nURS:Xa)[R "UUR S9upVXTS'XdS'U$) aGenerate parameters dependent on the input data. Args: params (dict[str, Any]): Parameters from the previous transform. data (dict[str, Any]): Input data. Returns: dict[str, np.ndarray | None]: Dictionary with the following keys: - "snow_point" (np.ndarray | None): The snow point threshold. - "snow_texture" (np.ndarray | None): The snow texture overlay. - "sparkle_mask" (np.ndarray | None): The sparkle mask for the snow effect. shapeN)rrrr) img_shaperandom_generatorrr)runiformrrrgenerate_snow_texturesr)rprdata image_shaperesultrrs rqget_params_dependent_on_data'RandomSnow.get_params_dependent_on_datas}$Wobq) ..00$2G2GH    ;;) #)/)F)F%!%!6!6* &L&2> "%1> " rt)rrr)g@皙?333333?rr)rrrtuple[float, float]rrrr) rrrrrrrrrrrwr)rdict[str, Any]rrrwzdict[str, np.ndarray | None] rxryrzr{rr(r~rrrr}rrs@rqrMrMsIV-,-#&0:/7  . -    "@ "@"@! "@ ! "@  "@ "@H!!! & !!rtrMc^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr SSjr S r U=r $)rJiCas Adds gravel-like artifacts to the input image. This transform simulates the appearance of gravel or small stones scattered across specific regions of an image. It's particularly useful for augmenting datasets of road or terrain images, adding realistic texture variations. Args: gravel_roi (tuple[float, float, float, float]): Region of interest where gravel will be added, specified as (x_min, y_min, x_max, y_max) in relative coordinates [0, 1]. Default: (0.1, 0.4, 0.9, 0.9). number_of_patches (int): Number of gravel patch regions to generate within the ROI. Each patch will contain multiple gravel particles. Default: 2. p (float): Probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 Number of channels: 3 Note: - The gravel effect is created by modifying the saturation channel in the HLS color space. - Gravel particles are distributed within randomly generated patches inside the specified ROI. - This transform is particularly useful for: * Augmenting datasets for road condition analysis * Simulating variations in terrain for computer vision tasks * Adding realistic texture to synthetic images of outdoor scenes Mathematical Formulation: For each gravel patch: 1. A rectangular region is randomly generated within the specified ROI. 2. Within this region, multiple gravel particles are placed. 3. For each particle: - Random (x, y) coordinates are generated within the patch. - A random radius (r) between 1 and 3 pixels is assigned. - A random saturation value (sat) between 0 and 255 is assigned. 4. The saturation channel of the image is modified for each particle: image_hls[y-r:y+r, x-r:x+r, 1] = sat Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) # Default usage >>> transform = A.RandomGravel(p=1.0) >>> augmented_image = transform(image=image)["image"] # Custom ROI and number of patches >>> transform = A.RandomGravel( ... gravel_roi=(0.2, 0.2, 0.8, 0.8), ... number_of_patches=5, ... p=1.0 ... ) >>> augmented_image = transform(image=image)["image"] # Combining with other transforms >>> transform = A.Compose([ ... A.RandomGravel(p=0.7), ... A.RandomBrightnessContrast(p=0.5), ... ]) >>> augmented_image = transform(image=image)["image"] References: - Road surface textures: https://en.wikipedia.org/wiki/Road_surface - HLS color space: https://en.wikipedia.org/wiki/HSL_and_HSV cR\rSrSr%S\S'\"SS9rS\S'\"SS 9S S j5rS r g )RandomGravel.InitSchemai!tuple[float, float, float, float] gravel_roigernumber_of_patchesrirjcURupp4SUs=::a Us=:aS::aO OSUs=::a Us=:aS::dO [SURS35eU$)NrrzInvalid gravel_roi. Got: .)rrn)rpgravel_lower_xgravel_lower_ygravel_upper_xgravel_upper_ys rq_validate_gravel_roi,RandomGravel.InitSchema._validate_gravel_roisTMQ__ JNN<<1[TU]US9 XlX lgr)rrrr)rprrrrs rqrRandomGravel.__init__s 1$!2rtcUup#pE[XB- XS- -5nUS-n[R"US/[RS9nURR X$U5USS2S4'URR X5U5USS2S4'U$)aGenerate gravel particles within a specified rectangular region. Args: rectangular_roi (tuple[int, int, int, int]): The rectangular region where gravel particles will be generated, specified as (x_min, y_min, x_max, y_max) in pixel coordinates. Returns: np.ndarray: An array of gravel particles with shape (count, 2), where count is the number of particles. Each row contains the (x, y) coordinates of a gravel particle. rrNrr)absremptyint64rintegers) rprectangular_roix_miny_minx_maxy_maxareacountgravelss rqgenerate_gravel_patch"RandomGravel.generate_gravel_patchs&5"eEMem45 ((E1:RXX6--66uUK1 --66uUK1 rtc .[R"X5$)aLApply the gravel effect to the input image. Args: img (np.ndarray): The input image to apply the gravel effect to. gravels_infos (list[Any]): Information about the gravel particles. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied gravel effect. )r add_gravel)rpr gravels_infosrs rqrRandomGravel.applys"  44rtc USSSup4S[URXCXC/55upVpxXu- n X- n /n [UR5GHbn URR U S-U S-5n URR U S-U S-5nURR XWU - 5nURR XhU- 5nX-S-n[U5Hn URR XU -5nURR UUU-5nURR SS 5nURR S S 5nU R [UU- S 5[UU-US- 5[UU- S 5[UU-US- 5U/5 M GMe S [R"U [RS 90$)a>Generate parameters dependent on the input data. Args: params (dict[str, Any]): Parameters from the previous transform. data (dict[str, Any]): Input data. Returns: dict[str, np.ndarray]: Dictionary with the following keys: - "gravels_infos" (np.ndarray): Information about the gravel particles. rNrc3@# UHup[X-5v M g7fNr).0coorddims rq .s & /cC  /csr rrr[rrr) ziprrangerrrappendmaxminrrr)rprrheightwidthrrrr roi_width roi_height gravels_info_ patch_width patch_heightpatch_xpatch_y num_particlesxyrsats rqr)RandomGravel.get_params_dependent_on_datas w+ & /24??UTYDb/c& "eM ]  t--.A..00b)q.QK>>11*2BJRSOTLnn,,UK4GHGnn,,UL4HIG)7C?M=)NN**7k4IJNN**7Gl4JKNN**1a0nn,,Q4##AE1 AE6A:.AE1 AE519-  */6 ,bhh!GHHrt)rr))r皙??r@rr)rrrrrr)rztuple[int, int, int, int]rwr)rrr list[Any]rrrwr)rrrrrwdict[str, np.ndarray]) rxryrzr{rr(r~rrrrr}rrs@rqrJrJCsFP , 9M!" 3533  332 .5 5!5 5  5&7I7I7I  7I7IrtrJc^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) rKia Adds rain effects to an image. This transform simulates rainfall by overlaying semi-transparent streaks onto the image, creating a realistic rain effect. It can be used to augment datasets for computer vision tasks that need to perform well in rainy conditions. Args: slant_range (tuple[float, float]): Range for the rain slant angle in degrees. Negative values slant to the left, positive to the right. Default: (-10, 10). drop_length (int | None): Length of the rain drops in pixels. If None, drop length will be automatically calculated as height // 8. This allows the rain effect to scale with the image size. Default: None drop_width (int): Width of the rain drops in pixels. Default: 1. drop_color (tuple[int, int, int]): Color of the rain drops in RGB format. Default: (200, 200, 200). blur_value (int): Blur value for simulating rain effect. Rainy views are typically blurry. Default: 7. brightness_coefficient (float): Coefficient to adjust the brightness of the image. Rainy scenes are usually darker. Should be in the range (0, 1]. Default: 0.7. rain_type (Literal["drizzle", "heavy", "torrential", "default"]): Type of rain to simulate. p (float): Probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 Number of channels: 3 Note: - The rain effect is created by drawing semi-transparent lines on the image. - The slant of the rain can be controlled to simulate wind effects. - Different rain types (drizzle, heavy, torrential) adjust the density and appearance of the rain. - The transform also adjusts image brightness and applies a blur to simulate the visual effects of rain. - This transform is particularly useful for: * Augmenting datasets for autonomous driving in rainy conditions * Testing the robustness of computer vision models to weather effects * Creating realistic rainy scenes for image editing or film production Mathematical Formulation: For each raindrop: 1. Start position (x1, y1) is randomly generated within the image. 2. End position (x2, y2) is calculated based on drop_length and slant: x2 = x1 + drop_length * sin(slant) y2 = y1 + drop_length * cos(slant) 3. A line is drawn from (x1, y1) to (x2, y2) with the specified drop_color and drop_width. 4. The image is then blurred and its brightness is adjusted. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) # Default usage >>> transform = A.RandomRain(p=1.0) >>> rainy_image = transform(image=image)["image"] # Custom rain parameters >>> transform = A.RandomRain( ... slant_range=(-15, 15), ... drop_length=30, ... drop_width=2, ... drop_color=(180, 180, 180), ... blur_value=5, ... brightness_coefficient=0.8, ... p=1.0 ... ) >>> rainy_image = transform(image=image)["image"] # Simulating heavy rain >>> transform = A.RandomRain(rain_type="heavy", p=1.0) >>> heavy_rain_image = transform(image=image)["image"] References: - Rain visualization techniques: https://developer.nvidia.com/gpugems/gpugems3/part-iv-image-effects/chapter-27-real-time-rain-rendering - Weather effects in computer vision: https://www.sciencedirect.com/science/article/pii/S1077314220300692 c\rSrSr%S\S'S\S'\"SS9rS\S 'S \S '\"SS9rS\S '\"S SS9rS\S'S\S'Sr g)RandomRain.InitSchemaiQzAnnotated[tuple[float, float], AfterValidator(nondecreasing), AfterValidator(check_range_bounds(-MAX_RAIN_ANGLE, MAX_RAIN_ANGLE))] slant_range int | None drop_lengthrrr drop_widthtuple[int, int, int] drop_color blur_valuerrlerbrightness_coefficient4Literal['drizzle', 'heavy', 'torrential', 'default'] rain_typeruN) rxryrzr{r|rrIrLrOr}rurtrqr~rEQsN   1+ C%((1+ C%(-q(99GGrtr~c t>[T U]US9 XlX lX0lX@lXPlX`lXplgr) rrrFrHrIrKrLrOrQ) rprFrHrIrKrLrOrQrrs rqrRandomRain.__init__^s; 1&&$$$&<#"rtc [U5 [R"UUUURURUR UR U5$)aApply the rain effect to the input image. Args: img (np.ndarray): The input image to apply the rain effect to. slant (float): The slant angle of the rain. drop_length (int): The length of the rain drops. rain_drops (np.ndarray): The coordinates of the rain drops. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied rain effect. )r radd_rainrIrKrLrO)rprslantrH rain_dropsrs rqrRandomRain.applyrsG* c    OO OO OO  ' '   rtcUSSSup4URS:XaUS-nO.URS:XaUnOURS:XaUS-nOUS-nURc[S US -5O URnURR"UR 6nUS :a5UR RS S /XCU- /US4[RS 9nUn O#[R"S [RS9n XgU S.$)aGenerate parameters dependent on the input data. Args: params (dict[str, Any]): Parameters from the previous transform. data (dict[str, Any]): Input data. Returns: dict[str, Any]: Dictionary with the following keys: - "drop_length" (int): The length of the rain drops. - "slant" (float): The slant angle of the rain. - "rain_drops" (np.ndarray): The coordinates of the rain drops. rNrdrizzleheavy torrentialr[rr)lowhighsizer)rrr)rHrVrW) rQrHr-rrrFrrrint32r) rprrr/r0 num_dropsrHrVcoordsrWs rqr'RandomRain.get_params_dependent_on_datas$w+  >>Y &! I ^^w &I ^^| + I! I-1-=-=-Ec!Vq[)4K[K[ &&(8(89 q=**33Fk12^hh 4F  J&9J**UUrt)rLrOrKrHrIrQrF))ir Nr)rfrfffffff?defaultr)rFrrHrGrIrrKrJrLrrOrrQrPrr) rrrVrrHrrWrrrrwrrrrrrwrrrs@rqrKrKsIV H, H,5"&+:(+JS#(# # # ) #  #!&#H# ##(               D0V0V0V  0V0VrtrKc^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) rHia! Simulates fog for the image by adding random fog-like artifacts. This transform creates a fog effect by generating semi-transparent overlays that mimic the visual characteristics of fog. The fog intensity and distribution can be controlled to create various fog-like conditions. An image size dependent Gaussian blur is applied to the resulting image Args: fog_coef_range (tuple[float, float]): Range for fog intensity coefficient. Should be in [0, 1] range. alpha_coef (float): Transparency of the fog circles. Should be in [0, 1] range. Default: 0.08. p (float): Probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 Number of channels: 3 Note: - The fog effect is created by overlaying semi-transparent circles on the image. - Higher fog coefficient values result in denser fog effects. - The fog is typically denser in the center of the image and gradually decreases towards the edges. - Image is blurred to decrease the sharpness - This transform is useful for: * Simulating various weather conditions in outdoor scenes * Data augmentation for improving model robustness to foggy conditions * Creating atmospheric effects in image editing Mathematical Formulation: For each fog particle: 1. A position (x, y) is randomly generated within the image. 2. A circle with random radius is drawn at this position. 3. The circle's alpha (transparency) is determined by the alpha_coef. 4. These circles are overlaid on the original image to create the fog effect. 5. A Gaussian blur dependent on the shorter dimension is applied The final pixel value is calculated as: output = blur((1 - alpha) * original_pixel + alpha * fog_color) where alpha is influenced by the fog_coef and alpha_coef parameters. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) # Default usage >>> transform = A.RandomFog(p=1.0) >>> foggy_image = transform(image=image)["image"] # Custom fog intensity range >>> transform = A.RandomFog(fog_coef_lower=0.3, fog_coef_upper=0.8, p=1.0) >>> foggy_image = transform(image=image)["image"] # Adjust fog transparency >>> transform = A.RandomFog(fog_coef_lower=0.2, fog_coef_upper=0.5, alpha_coef=0.1, p=1.0) >>> foggy_image = transform(image=image)["image"] References: - Fog: https://en.wikipedia.org/wiki/Fog - Atmospheric perspective: https://en.wikipedia.org/wiki/Aerial_perspective c8\rSrSr%S\S'\"SSS9rS\S'S rg ) RandomFog.InitSchemai rfog_coef_rangerrrrNr alpha_coefruN)rxryrzr{r|rrpr}rurtrqr~rm s  "Q1- E-rtr~c8>[TU]US9 X lXlgr)rrrnrp)rprprnrrs rqrRandomFog.__init__s 1,$rtc `[U5 [R"UUURUU5$)aApply the fog effect to the input image. Args: img (np.ndarray): The input image to apply the fog effect to. particle_positions (list[tuple[int, int]]): The coordinates of the fog particles. radiuses (list[int]): The radii of the fog particles. intensity (float): The intensity of the fog. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied fog effect. )r radd_fogrp)rprparticle_positionsradiuses intensityrs rqrRandomFog.applys0* c~~   OO     rtcURR"UR6nUSSSnUupV[S[ US-U-55n/nS[ R "U55upUn Un Sn SnS nX:aX:aX:aX-n[ UXw-- U-S-5n[U5HbnURRXS-- XS--5nURRXS-- XS--5nURUU45 Md [ U SU - -5n [ U SU - -5n US- nX:a X:aX:aM[R"U[U5UUR5nUUUS .$) aGenerate parameters dependent on the input data. Args: params (dict[str, Any]): Parameters from the previous transform. data (dict[str, Any]): Input data. Returns: dict[str, Any]: Dictionary with the following keys: - "intensity" (float): The intensity of the fog. - "particle_positions" (list[tuple[int, int]]): The coordinates of the fog particles. - "radiuses" (list[int]): The radii of the fog particles. rNrrr[c38# UHn[U5v M g7fr!r")r#r:s rqr&9RandomFog.get_params_dependent_on_data..[sM.Lc!ff.Lsrr r)rurwrv)rrrnr-r fgeometriccenterr+rr,rget_fog_particle_radiuseslenr)rprrrwr image_height image_widthfog_region_sizerucenter_xcenter_y current_widthcurrent_height shrink_factormax_iterations iterationrparticles_in_regionr4r:r;rvs rqr&RandomFog.get_params_dependent_on_data<s&NN**D,?,?@ Wobq) $/! a[A%5 %A!BCNj.?.? .LM$ %  -.2RW`Wq 1D"%9:YFK# ./NN**1111NN**2222#))1a&10 ]1B CDM 1}3D!EFN NI/-.2RW`Wq233  " #   ! !  #5"   rt)rprn)g{Gz?)rrr)rprrnrrr) rrruzlist[tuple[int, int]]rv list[int]rwrrrrwrrjrrs@rqrHrHsAF.,.!.6 %%,%  %%  2         >> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [1000, 1000, 3], dtype=np.uint8) # Default sun flare (overlay method) >>> transform = A.RandomSunFlare(p=1.0) >>> flared_image = transform(image=image)["image"] # Physics-based sun flare with custom parameters # Default sun flare >>> transform = A.RandomSunFlare(p=1.0) >>> flared_image = transform(image=image)["image"] # Custom sun flare parameters >>> transform = A.RandomSunFlare( ... flare_roi=(0.1, 0, 0.9, 0.3), ... angle_range=(0.25, 0.75), ... num_flare_circles_range=(5, 15), ... src_radius=200, ... src_color=(255, 200, 100), ... method="physics_based", ... p=1.0 ... ) >>> flared_image = transform(image=image)["image"] References: - Lens flare: https://en.wikipedia.org/wiki/Lens_flare - Alpha compositing: https://en.wikipedia.org/wiki/Alpha_compositing - Diffraction: https://en.wikipedia.org/wiki/Diffraction - Chromatic aberration: https://en.wikipedia.org/wiki/Chromatic_aberration - Screen blending: https://en.wikipedia.org/wiki/Blend_modes#Screen cz\rSrSr%S\S'\"SS9rS\S'S\S 'S \S 'S \S 'S\S'\"SS9SSj5rSr g)RandomSunFlare.InitSchemair flare_roirrr src_radiustuple[int, ...] src_colorr angle_rangefAnnotated[tuple[int, int], AfterValidator(check_range_bounds(1, None)), AfterValidator(nondecreasing)]num_flare_circles_range#Literal['overlay', 'physics_based']rrirjcURunnnnSUs=::a Us=:aS::aO OSUs=::a Us=:aS::dO [SUR35eU$)NrrzInvalid flare_roi. Got: )rrn)rpflare_center_lower_xflare_center_lower_yflare_center_upper_xflare_center_upper_ys rq_validate_parameters.RandomSunFlare.InitSchema._validate_parameterssc  $$$$-I0DII0L3GL1L #;DNN;K!LMMKrtruNrv) rxryrzr{r|rrrrr}rurtrqr~rsO441+ C%""  "  43 g &  ' rtr~ch>[TU]US9 X@lXPlX lX0lXlX`lgr)rrrrrrrr) rprrrrrrrrs rqrRandomSunFlare.__init__(s5 1&'>$$"" rtc @[U5 URS:Xa.[R"UUURUR U5$URS:Xa.[R "UUURUR U5$[SUR35e)aApply the sun flare effect to the input image. Args: img (np.ndarray): The input image to apply the sun flare effect to. flare_center (tuple[float, float]): The center of the sun. circles (list[Any]): The circles to apply the sun flare effect to. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied sun flare effect. overlay physics_basedzInvalid method: )r rradd_sun_flare_overlayrradd_sun_flare_physics_basedrn)rpr flare_centercirclesrs rqrRandomSunFlare.apply<s& c ;;) #//   ;;/ )55  +DKK=9::rtc ^^^USSSup4[R"US-US--5nS[R-URR"UR 6-mUR upgp[X@RR Xh5-5m[X0RR Xy5-5mURR"UR6n [S[US-55n [S[US-55n [[UR5S-5n S UUU4Sjjn[T*UT- U 5nUVs/sH nU"U5PM nn/n[U 5HnURR SS5nURRU5nURRSU 5nURVs/sH,nURR[UU - S 5U5PM. nnURU[US 5[US54[US 5[!U545 M UTT4S .$s snfs snf) a}Generate parameters dependent on the input data. Args: params (dict[str, Any]): Parameters from the previous transform. data (dict[str, Any]): Input data. Returns: dict[str, Any]: Dictionary with the following keys: - "circles" (list[Any]): The circles to apply the sun flare effect to. - "flare_center" (tuple[float, float]): The center of the sun. rNrr{Gz?皙?ct>TU[R"T5--TU[R"T5--4$r!)mathcossin)tangleflare_center_xflare_center_ys rqline9RandomSunFlare.get_params_dependent_on_data..lines7TXXe_!44TXXe_!44 rt皙?rr[)rr)rrrwr)rsqrtpirrrrrrrr-rr+choicer,powtuple)rprrr/r0diagonalrrrr num_circles step_size max_radius color_rangert_rangerpointsrr4alphapointradccolorsrrrs @@@rqr+RandomSunFlare.get_params_dependent_on_datacs&"w+ 99VQY12DGG dnn44d6F6FGG&*^^"eU^^%;%;E%IIJVnn&<&>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) # Default usage >>> transform = A.RandomShadow(p=1.0) >>> shadowed_image = transform(image=image)["image"] # Custom shadow parameters >>> transform = A.RandomShadow( ... shadow_roi=(0.2, 0.2, 0.8, 0.8), ... num_shadows_limit=(2, 4), ... shadow_dimension=8, ... shadow_intensity_range=(0.3, 0.7), ... p=1.0 ... ) >>> shadowed_image = transform(image=image)["image"] # Combining with other transforms >>> transform = A.Compose([ ... A.RandomShadow(p=0.5), ... A.RandomBrightnessContrast(p=0.5), ... ]) >>> augmented_image = transform(image=image)["image"] References: - Shadow detection and removal: https://www.sciencedirect.com/science/article/pii/S1047320315002035 - Shadows in computer vision: https://en.wikipedia.org/wiki/Shadow_detection cf\rSrSr%S\S'S\S'\"SS9rS\S 'S \S '\"S S 9SSj5rSr g)RandomShadow.InitSchemair shadow_roirnum_shadows_limitr[rrshadow_dimensionrshadow_intensity_rangerirjcURupp4SUs=::a Us=::aS::aO OSUs=::a Us=::aS::dO [SUR35eU$)NrrzInvalid shadow_roi. Got: )rrn)rpshadow_lower_xshadow_lower_yshadow_upper_xshadow_upper_ys rq_validate_shadows)RandomShadow.InitSchema._validate_shadowssRMQ__ JNN=.=A=Q.Eo\jEonoEo #[TU]US9 XlX0lX lX@lgr)rrrrrr)rprrrrrrs rqrRandomShadow.__init__ s, 1$ 0!2&<#rtc 0[R"XU5$)aApply the shadow effect to the input image. Args: img (np.ndarray): The input image to apply the shadow effect to. vertices_list (list[np.ndarray]): The vertices of the shadow polygons. intensities (np.ndarray): The intensities of the shadows. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied shadow effect. )r add_shadow)rpr vertices_list intensitiesrs rqrRandomShadow.applys&  [AArtc ,USSSup4URR"UR6nURupgp[ Xd-5n[ X-5n[ Xs-5n[ X-5n [ U5V s/sH`n [ R"URRUUURS9URRUU URS9/SS9PMb n n URR"URSU06n XS.$s sn f) aGenerate parameters dependent on the input data. Args: params (dict[str, Any]): Parameters from the previous transform. data (dict[str, Any]): Input data. Returns: dict[str, list[np.ndarray]]: Dictionary with the following keys: - "vertices_list" (list[np.ndarray]): The vertices of the shadow polygons. - "intensities" (np.ndarray): The intensities of the shadows. rNr)raraxisra)rr) rrrrrr+rstackrrrrr) rprrr/r0 num_shadowsrrrrr4rrs rqr)RandomShadow.get_params_dependent_on_data.s7"w+ nn,,d.D.DE %)__"eEM"EM"EN#EN#$;'! ( HH))22!223 ))22!223  (!  (++33  ( (  "/KK3 s>A'D)rrrr))rrrr)rrr(rrr) rrrrrrrrrr) rrrzlist[np.ndarray]rrrrrwr)rrrrrwzdict[str, list[np.ndarray]]rrs@rqrLrLsHT,49G-3 !6@ =5 =+ = = !4 =  = =B B(B B  B  B*5L5L5L % 5L5LrtrLc^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) rOifu Randomly change the relationship between bright and dark areas of the image by manipulating its tone curve. This transform applies a random S-curve to the image's tone curve, adjusting the brightness and contrast in a non-linear manner. It can be applied to the entire image or to each channel separately. Args: scale (float): Standard deviation of the normal distribution used to sample random distances to move two control points that modify the image's curve. Values should be in range [0, 1]. Higher values will result in more dramatic changes to the image. Default: 0.1 per_channel (bool): If True, the tone curve will be applied to each channel of the input image separately, which can lead to color distortion. If False, the same curve is applied to all channels, preserving the original color relationships. Default: False p (float): Probability of applying the transform. Default: 0.5 Targets: image Image types: uint8, float32 Number of channels: Any Note: - This transform modifies the image's histogram by applying a smooth, S-shaped curve to it. - The S-curve is defined by moving two control points of a quadratic Bézier curve. - When per_channel is False, the same curve is applied to all channels, maintaining color balance. - When per_channel is True, different curves are applied to each channel, which can create color shifts. - This transform can be used to adjust image contrast and brightness in a more natural way than linear transforms. - The effect can range from subtle contrast adjustments to more dramatic "vintage" or "faded" looks. Mathematical Formulation: 1. Two control points are randomly moved from their default positions (0.25, 0.25) and (0.75, 0.75). 2. The new positions are sampled from a normal distribution: N(μ, σ²), where μ is the original position and alpha is the scale parameter. 3. These points, along with fixed points at (0, 0) and (1, 1), define a quadratic Bézier curve. 4. The curve is applied as a lookup table to the image intensities: new_intensity = curve(original_intensity) Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) # Apply a random tone curve to all channels together >>> transform = A.RandomToneCurve(scale=0.1, per_channel=False, p=1.0) >>> augmented_image = transform(image=image)['image'] # Apply random tone curves to each channel separately >>> transform = A.RandomToneCurve(scale=0.2, per_channel=True, p=1.0) >>> augmented_image = transform(image=image)['image'] References: - "What Else Can Fool Deep Learning? Addressing Color Constancy Errors on Deep Neural Network Performance": https://arxiv.org/abs/1912.06960 - Bézier curve: https://en.wikipedia.org/wiki/B%C3%A9zier_curve#Quadratic_B%C3%A9zier_curves - Tone mapping: https://en.wikipedia.org/wiki/Tone_mapping c8\rSrSr%\"SSS9rS\S'S\S'S rg ) RandomToneCurve.InitSchemairrrorscalebool per_channelruN)rxryrzr{rrr|r}rurtrqr~rs! u rtr~c8>[TU]US9 XlX lgr)rrrr)rprrrrs rqrRandomToneCurve.__init__s 1 &rtc 0[R"XU5$)aApply the tone curve to the input image. Args: img (np.ndarray): The input image to apply the tone curve to. low_y (float | np.ndarray): The lower control point of the tone curve. high_y (float | np.ndarray): The upper control point of the tone curve. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied tone curve. )rmove_tone_curve)rprlow_yhigh_yrs rqrRandomToneCurve.applys&%%c&99rtc NSU;aUSOUSSn[U5nUR(aUS:way[R"URR SUR U4S9SS5[R"URR SUR U4S9SS5S.$[R"URR SUR S 9SS5n[R"URR SUR S 9SS5nXVS.$) aGenerate parameters dependent on the input data. Args: params (dict[str, Any]): Parameters from the previous transform. data (dict[str, Any]): Input data. Returns: dict[str, Any]: Dictionary with the following keys: - "low_y" (float | np.ndarray): The lower control point of the tone curve. - "high_y" (float | np.ndarray): The upper control point of the tone curve. imagerrr?)locrrag?)rr)rr)r rrcliprnormalr)rprrr num_channelsrrs rqr,RandomToneCurve.get_params_dependent_on_datas#"")DW d8nQ6G'.     1))00 "jj*_1 ''))00 "jj*_1  *--44TZZ4PRSUVW..55$djj5QSTVWX11rt)rr)rFr)rrrrrr) rrrfloat | np.ndarrayrrrrrwrrjrrs@rqrOrOfs;z,! '''  '': :":# :  :  :*.2.2.2  .2.2rtrOc^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) r;iaRandomly change hue, saturation and value of the input image. This transform adjusts the HSV (Hue, Saturation, Value) channels of an input RGB image. It allows for independent control over each channel, providing a wide range of color and brightness modifications. Args: hue_shift_limit (float | tuple[float, float]): Range for changing hue. If a single float value is provided, the range will be (-hue_shift_limit, hue_shift_limit). Values should be in the range [-180, 180]. Default: (-20, 20). sat_shift_limit (float | tuple[float, float]): Range for changing saturation. If a single float value is provided, the range will be (-sat_shift_limit, sat_shift_limit). Values should be in the range [-255, 255]. Default: (-30, 30). val_shift_limit (float | tuple[float, float]): Range for changing value (brightness). If a single float value is provided, the range will be (-val_shift_limit, val_shift_limit). Values should be in the range [-255, 255]. Default: (-20, 20). p (float): Probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 Number of channels: 3 Note: - The transform first converts the input RGB image to the HSV color space. - Each channel (Hue, Saturation, Value) is adjusted independently. - Hue is circular, so it wraps around at 180 degrees. - For float32 images, the shift values are applied as percentages of the full range. - This transform is particularly useful for color augmentation and simulating different lighting conditions. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> transform = A.HueSaturationValue( ... hue_shift_limit=20, ... sat_shift_limit=30, ... val_shift_limit=20, ... p=0.7 ... ) >>> result = transform(image=image) >>> augmented_image = result["image"] References: HSV color space: https://en.wikipedia.org/wiki/HSL_and_HSV c4\rSrSr%S\S'S\S'S\S'Srg)HueSaturationValue.InitSchemai4r$hue_shift_limitsat_shift_limitval_shift_limitruNrrurtrqr~r4s++++++rtr~c>[TU]US9 [SU5Ul[SU5Ul[SU5UlgNrr)rrr rrr)rprrrrrs rqrHueSaturationValue.__init__9sE 1#$9?K#$9?K#$9?Krtc [U5(d[U5(d Sn[U5e[R"XX45$)aApply the hue, saturation, and value shifts to the input image. Args: img (np.ndarray): The input image to apply the hue, saturation, and value shifts to. hue_shift (int): The hue shift value. sat_shift (int): The saturation shift value. val_shift (int): The value (brightness) shift value. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied hue, saturation, and value shifts. zHHueSaturationValue transformation expects 1-channel or 3-channel images.)rr TypeErrorr shift_hsv)rpr hue_shift sat_shift val_shiftrmsgs rqrHueSaturationValue.applyEs<*C  );C)@)@\CC.  EErtcURR"UR6URR"UR6URR"UR6S.$)a(Generate parameters dependent on the input data. Returns: dict[str, float]: Dictionary with the following keys: - "hue_shift" (float): The hue shift value. - "sat_shift" (float): The saturation shift value. - "val_shift" (float): The value (brightness) shift value. )rr r )rrrrrros rqrHueSaturationValue.get_params_sV//1E1EF//1E1EF//1E1EF  rt)rrr)ir\)irr)rtuple[float, float] | floatrrrrrr) rrrrr rr rrrrwrrwdict[str, float]rrs@rqr;r;s6p,,,8A7@7@ L4 L5 L5 L  L LF FF F  F  F F4  rtr;ch^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) rTipa Invert all pixel values above a threshold. This transform applies a solarization effect to the input image. Solarization is a phenomenon in photography in which the image recorded on a negative or on a photographic print is wholly or partially reversed in tone. Dark areas appear light or light areas appear dark. In this implementation, all pixel values above a threshold are inverted. Args: threshold_range (tuple[float, float]): Range for solarizing threshold as a fraction of maximum value. The threshold_range should be in the range [0, 1] and will be multiplied by the maximum value of the image type (255 for uint8 images or 1.0 for float images). Default: (0.5, 0.5) (corresponds to 127.5 for uint8 and 0.5 for float32). p (float): Probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 Number of channels: Any Note: - For uint8 images, pixel values above the threshold are inverted as: 255 - pixel_value - For float32 images, pixel values above the threshold are inverted as: 1.0 - pixel_value - The threshold is applied to each channel independently - The threshold is calculated in two steps: 1. Sample a value from threshold_range 2. Multiply by the image's maximum value: * For uint8: threshold = sampled_value * 255 * For float32: threshold = sampled_value * 1.0 - This transform can create interesting artistic effects or be used for data augmentation Examples: >>> import numpy as np >>> import albumentations as A >>> # Solarize uint8 image with fixed threshold at 50% of max value (127.5) >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> transform = A.Solarize(threshold_range=(0.5, 0.5), p=1.0) >>> solarized_image = transform(image=image)['image'] >>> # Solarize uint8 image with random threshold between 40-60% of max value (102-153) >>> transform = A.Solarize(threshold_range=(0.4, 0.6), p=1.0) >>> solarized_image = transform(image=image)['image'] >>> # Solarize float32 image at 50% of max value (0.5) >>> image = np.random.rand(100, 100, 3).astype(np.float32) >>> transform = A.Solarize(threshold_range=(0.5, 0.5), p=1.0) >>> solarized_image = transform(image=image)['image'] Mathematical Formulation: Let f be a value sampled from threshold_range (min, max). For each pixel value p: threshold = f * max_value if p > threshold: p_new = max_value - p else: p_new = p Where max_value is 255 for uint8 images and 1.0 for float32 images. See Also: Invert: For inverting all pixel values regardless of a threshold. c \rSrSr%S\S'Srg)Solarize.InitSchemairthreshold_rangeruNrrurtrqr~rs   rtr~c,>[TU]US9 Xlgr)rrr)rprrrs rqrSolarize.__init__s 1.rtc .[R"X5$)a7Apply the solarize effect to the input image. Args: img (np.ndarray): The input image to apply the solarize effect to. threshold (float): The threshold value. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied solarize effect. )rsolarize)rpr thresholdrs rqrSolarize.applyss..rtcLSURR"UR60$)zGenerate parameters dependent on the input data. Returns: dict[str, float]: Dictionary with the following key: - "threshold" (float): The threshold value. r)rrrros rqrSolarize.get_paramss$T^^33T5I5IJKKrt)r)rr)rrrr)rrrrrrrwrrrrs@rqrTrTpsLCJ , 0:/,/ // /LLrtrTcx^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) rEia Reduces the number of bits for each color channel in the image. This transform applies color posterization, a technique that reduces the number of distinct colors used in an image. It works by lowering the number of bits used to represent each color channel, effectively creating a "poster-like" effect with fewer color gradations. Args: num_bits (int | tuple[int, int] | list[int] | list[tuple[int, int]]): Defines the number of bits to keep for each color channel. Can be specified in several ways: - Single int: Same number of bits for all channels. Range: [1, 7]. - tuple of two ints: (min_bits, max_bits) to randomly choose from. Range for each: [1, 7]. - list of three ints: Specific number of bits for each channel [r_bits, g_bits, b_bits]. - list of three tuples: Ranges for each channel [(r_min, r_max), (g_min, g_max), (b_min, b_max)]. Default: 4 p (float): Probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 Number of channels: Any Note: - The effect becomes more pronounced as the number of bits is reduced. - This transform can create interesting artistic effects or be used for image compression simulation. - Posterization is particularly useful for: * Creating stylized or retro-looking images * Reducing the color palette for specific artistic effects * Simulating the look of older or lower-quality digital images * Data augmentation in scenarios where color depth might vary Mathematical Background: For an 8-bit color channel, posterization to n bits can be expressed as: new_value = (old_value >> (8 - n)) << (8 - n) This operation keeps the n most significant bits and sets the rest to zero. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) # Posterize all channels to 3 bits >>> transform = A.Posterize(num_bits=3, p=1.0) >>> posterized_image = transform(image=image)["image"] # Randomly posterize between 2 and 5 bits >>> transform = A.Posterize(num_bits=(2, 5), p=1.0) >>> posterized_image = transform(image=image)["image"] # Different bits for each channel >>> transform = A.Posterize(num_bits=[3, 5, 2], p=1.0) >>> posterized_image = transform(image=image)["image"] # Range of bits for each channel >>> transform = A.Posterize(num_bits=[(1, 3), (3, 5), (2, 4)], p=1.0) >>> posterized_image = transform(image=image)["image"] References: - Color Quantization: https://en.wikipedia.org/wiki/Color_quantization - Posterization: https://en.wikipedia.org/wiki/Posterization cR\rSrSr%S\S'\"S5\SSj55rSrg)Posterize.InitSchemai"-int | tuple[int, int] | list[tuple[int, int]]num_bitsc[U[5(aUS:d U[:a [S5eX4$[U[5(a/[ U5[ :aUVs/sHn[X"5PM sn$[X5$s snf)Nrz$num_bits must be in the range [1, 7]) isinstancerr-rnrrr,r.)clsr$is rq_validate_num_bits'Posterize.InitSchema._validate_num_bits%su (C((a<8e#3$%KLL ++(H--#h-$2F089199H/ /:s BruN)r$rrwz'tuple[int, int] | list[tuple[int, int]]) rxryrzr{r|r classmethodr)r}rurtrqr~r""s9??  $  0 05 0  % 0rtr~cB>[TU]US9 [SU5Ulg)Nrz-Union[tuple[int, int], list[tuple[int, int]]])rrr r$)rpr$rrs rqrPosterize.__init__3s$ 1LhW rtc .[R"X5$)aApply the posterize effect to the input image. Args: img (np.ndarray): The input image to apply the posterize effect to. num_bits (Literal[1, 2, 3, 4, 5, 6, 7] | list[Literal[1, 2, 3, 4, 5, 6, 7]]): The number of bits to keep for each color channel. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied posterize effect. )r posterize)rprr$rs rqrPosterize.apply;s$..rtc[UR[5(a6URVs/sHoRR"U6PM nnSU0$SURR"UR60$s snf)a Generate parameters dependent on the input data. Returns: dict[str, Any]: Dictionary with the following key: - "num_bits" (Literal[1, 2, 3, 4, 5, 6, 7] | list[Literal[1, 2, 3, 4, 5, 6, 7]]): The number of bits to keep for each color channel. r$)r&r$listrr)rpr(r$s rqrPosterize.get_paramsOsi dmmT * *<@MMJMq..2MHJ) )DNN22DMMBCCKs"A;)r$)r[r)r$r#rr)rrr$zALiteral[1, 2, 3, 4, 5, 6, 7] | list[Literal[1, 2, 3, 4, 5, 6, 7]]rrrwrrwrrrs@rqrErEsyAF0,0&CDX?X XX/ /T/ /  /( D DrtrEc^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr \ SSj5r S r U=r $)r7i^a Equalize the image histogram. This transform applies histogram equalization to the input image. Histogram equalization is a method in image processing of contrast adjustment using the image's histogram. Args: mode (Literal['cv', 'pil']): Use OpenCV or Pillow equalization method. Default: 'cv' by_channels (bool): If True, use equalization by channels separately, else convert image to YCbCr representation and use equalization by `Y` channel. Default: True mask (np.ndarray, callable): If given, only the pixels selected by the mask are included in the analysis. Can be: - A 1-channel or 3-channel numpy array of the same size as the input image. - A callable (function) that generates a mask. The function should accept 'image' as its first argument, and can accept additional arguments specified in mask_params. Default: None mask_params (list[str]): Additional parameters to pass to the mask function. These parameters will be taken from the data dict passed to __call__. Default: () p (float): Probability of applying the transform. Default: 0.5. Targets: image, volume Image types: uint8, float32 Number of channels: 1,3 Note: - When mode='cv', OpenCV's equalizeHist() function is used. - When mode='pil', Pillow's equalize() function is used. - The 'by_channels' parameter determines whether equalization is applied to each color channel independently (True) or to the luminance channel only (False). - If a mask is provided as a numpy array, it should have the same height and width as the input image. - If a mask is provided as a function, it allows for dynamic mask generation based on the input image and additional parameters. This is useful for scenarios where the mask depends on the image content or external data (e.g., bounding boxes, segmentation masks). Mask Function: When mask is a callable, it should have the following signature: mask_func(image, *args) -> np.ndarray - image: The input image (numpy array) - *args: Additional arguments as specified in mask_params The function should return a numpy array of the same height and width as the input image, where non-zero pixels indicate areas to be equalized. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> >>> # Using a static mask >>> mask = np.random.randint(0, 2, (100, 100), dtype=np.uint8) >>> transform = A.Equalize(mask=mask, p=1.0) >>> result = transform(image=image) >>> >>> # Using a dynamic mask function >>> def mask_func(image, bboxes): ... mask = np.ones_like(image[:, :, 0], dtype=np.uint8) ... for bbox in bboxes: ... x1, y1, x2, y2 = map(int, bbox) ... mask[y1:y2, x1:x2] = 0 # Exclude areas inside bounding boxes ... return mask >>> >>> transform = A.Equalize(mask=mask_func, mask_params=['bboxes'], p=1.0) >>> bboxes = [(10, 10, 50, 50), (60, 60, 90, 90)] # Example bounding boxes >>> result = transform(image=image, bboxes=bboxes) References: - OpenCV equalizeHist: https://docs.opencv.org/3.4/d6/dc7/group__imgproc__hist.html#ga7e54091f0c937d49bf84152a16f76d6e - Pillow ImageOps.equalize: https://pillow.readthedocs.io/en/stable/reference/ImageOps.html#PIL.ImageOps.equalize - Histogram Equalization: https://en.wikipedia.org/wiki/Histogram_equalization c>\rSrSr%S\S'S\S'S\S'S\S 'S rg ) Equalize.InitSchemaiLiteral['cv', 'pil']rkr by_channels&np.ndarray | Callable[..., Any] | Nonemask Sequence[str] mask_paramsruNrrurtrqr~r7s""44""rtr~cP>[TU]US9 XlX lX0lX@lgr)rrrkr9r;r=)rprkr9r;r=rrs rqrEqualize.__init__s+ 1 & &rtc [U5(d[U5(d [S5e[R"UUR UR US9$)a\Apply the equalization effect to the input image. Args: img (np.ndarray): The input image to apply the equalization effect to. mask (np.ndarray): The mask to apply the equalization effect to. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied equalization effect. zBEqualize transform is only supported for RGB and grayscale images.)rkr9r;)rrrnrequalizerkr9)rprr;rs rqrEqualize.applysMC  );C)@)@ab b ((   rtc[UR5(dSUR0$SUS0nURHnXB;a[SUS35eX$X4'M SUR"S0UD60$)a3Generate parameters dependent on the input data. Args: params (dict[str, Any]): Parameters from the previous transform. data (dict[str, Any]): Input data. Returns: dict[str, Any]: Dictionary with the following key: - "mask" (np.ndarray): The mask to apply the equalization effect to. r;rzRequired parameter 'z'' for mask function is missing in data.ru)callabler;r=KeyError)rprrr=keys rqr%Equalize.get_params_dependent_on_datas  ""DII& &W . ##C*3%/VW $yK  $ 0K011rtc0/[UR5Q$)zxReturn the list of parameters that are used for generating the mask. Returns: list[str]: List of parameter names. )r2r=ros rqtargets_as_paramsEqualize.targets_as_paramss)d&&'((rt)r9r;r=rk)cvTNrur) rkr8r9rr;r:r=r<rr)rrr;rrrrwrrj)rwz list[str])rxryrzr{rr(r~rrrpropertyrIr}rrs@rqr7r7^sN`#,#&* 7;%' '" ' '5 ' # '  ' ' *222  2:))rtr7c^\rSrSrSr"SS\5rS S U4SjjjrSSjrSSjr SSjr SS jr SS jr S r U=r$)rGi uRandomly changes the brightness and contrast of the input image. This transform adjusts the brightness and contrast of an image simultaneously, allowing for a wide range of lighting and contrast variations. It's particularly useful for data augmentation in computer vision tasks, helping models become more robust to different lighting conditions. Args: brightness_limit (float | tuple[float, float]): Factor range for changing brightness. If a single float value is provided, the range will be (-brightness_limit, brightness_limit). Values should typically be in the range [-1.0, 1.0], where 0 means no change, 1.0 means maximum brightness, and -1.0 means minimum brightness. Default: (-0.2, 0.2). contrast_limit (float | tuple[float, float]): Factor range for changing contrast. If a single float value is provided, the range will be (-contrast_limit, contrast_limit). Values should typically be in the range [-1.0, 1.0], where 0 means no change, 1.0 means maximum increase in contrast, and -1.0 means maximum decrease in contrast. Default: (-0.2, 0.2). brightness_by_max (bool): If True, adjusts brightness by scaling pixel values up to the maximum value of the image's dtype. If False, uses the mean pixel value for adjustment. Default: True. ensure_safe_range (bool): If True, adjusts alpha and beta to prevent overflow/underflow. This ensures output values stay within the valid range for the image dtype without clipping. Default: False. p (float): Probability of applying the transform. Default: 0.5. Targets: image, volume Image types: uint8, float32 Number of channels: Any Note: - The order of operation is: contrast adjustment, then brightness adjustment. - For uint8 images, the output is clipped to [0, 255] range. - For float32 images, the output is clipped to [0, 1] range. - The `brightness_by_max` parameter affects how brightness is adjusted: * If True, brightness adjustment is more pronounced and can lead to more saturated results. * If False, brightness adjustment is more subtle and preserves the overall lighting better. - This transform is useful for: * Simulating different lighting conditions * Enhancing low-light or overexposed images * Data augmentation to improve model robustness Mathematical Formulation: Let a be the contrast adjustment factor and β be the brightness adjustment factor. For each pixel value x: 1. Contrast adjustment: x' = clip((x - mean) * (1 + a) + mean) 2. Brightness adjustment: If brightness_by_max is True: x'' = clip(x' * (1 + β)) If brightness_by_max is False: x'' = clip(x' + β * max_value) Where clip() ensures values stay within the valid range for the image dtype. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) # Default usage >>> transform = A.RandomBrightnessContrast(p=1.0) >>> augmented_image = transform(image=image)["image"] # Custom brightness and contrast limits >>> transform = A.RandomBrightnessContrast( ... brightness_limit=0.3, ... contrast_limit=0.3, ... p=1.0 ... ) >>> augmented_image = transform(image=image)["image"] # Adjust brightness based on mean value >>> transform = A.RandomBrightnessContrast( ... brightness_limit=0.2, ... contrast_limit=0.2, ... brightness_by_max=False, ... p=1.0 ... ) >>> augmented_image = transform(image=image)["image"] References: - Brightness: https://en.wikipedia.org/wiki/Brightness - Contrast: https://en.wikipedia.org/wiki/Contrast_(vision) c>\rSrSr%S\S'S\S'S\S'S\S'Srg ) #RandomBrightnessContrast.InitSchemai] r$brightness_limitcontrast_limitrbrightness_by_maxensure_safe_rangeruNrrurtrqr~rO] s,,**rtr~c|>[TU]US9 [SU5Ul[SU5UlX0lX@lgr)rrr rPrQrRrS)rprPrQrRrSrrs rqr!RandomBrightnessContrast.__init__c sB 1 $%:>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (224, 224, 3), dtype=np.uint8) >>> >>> # Apply Gaussian noise with normalized std_range >>> transform = A.GaussNoise(std_range=(0.1, 0.2), p=1.0) # 10-20% of max value >>> noisy_image = transform(image=image)['image'] cL\rSrSr%S\S'S\S'S\S'\"SS S 9rS \S 'S rg)GaussNoise.InitSchemai r std_rangezhAnnotated[tuple[float, float], AfterValidator(check_range_bounds(-1, 1)), AfterValidator(nondecreasing)] mean_rangerrrrrMrnoise_scale_factorruN)rxryrzr{r|rrvr}rurtrqr~rs s0    $)Q1$5E5rtr~cP>[TU]US9 XlX lX0lX@lgr)rrrtrurrv)rprtrurrvrrs rqrGaussNoise.__init__ s+ 1"$&"4rtc .[R"X5$)aIApply the Gaussian noise to the input image. Args: img (np.ndarray): The input image to apply the Gaussian noise to. noise_map (np.ndarray): The noise map to apply to the image. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied Gaussian noise. r add_noiserpr noise_maprs rqrGaussNoise.apply! s"//rtc SU;aUSOUSSn[URnURR"UR6nURR"UR 6n[ R"SUR(aSOSURXf4XU4S.UURURS9nS U0$) a1Generate parameters dependent on the input data. Args: params (dict[str, Any]): Parameters from the previous transform. data (dict[str, Any]): Input data. Returns: dict[str, float]: Dictionary with the following key: - "noise_map" (np.ndarray): The noise map to apply to the image. rrrgaussian per_pixelsharedrurt noise_type spatial_moderrrj approximationrr}) r rrrrtrurgenerate_noiserrrvr)rprrrrjsigmarcr}s rqr'GaussNoise.get_params_dependent_on_data4 s ")DW d8nQ6G' 4 &&7~~%%t7))!(,(8(8h++#',e^L11!22 Y''rt)rurvrrt))rg)\(?rTrr) rtrrurrrrvrrrrrr}rrrrwrrprrs@rqr9r9 s)V 6, 6 *5*4 $% 5& 5( 5 5 " 5  5 50 00 0  0& ( ( (  ( (rtr9c^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) r<iW uApplies camera sensor noise to the input image, simulating high ISO settings. This transform adds random noise to an image, mimicking the effect of using high ISO settings in digital photography. It simulates two main components of ISO noise: 1. Color noise: random shifts in color hue 2. Luminance noise: random variations in pixel intensity Args: color_shift (tuple[float, float]): Range for changing color hue. Values should be in the range [0, 1], where 1 represents a full 360° hue rotation. Default: (0.01, 0.05) intensity (tuple[float, float]): Range for the noise intensity. Higher values increase the strength of both color and luminance noise. Default: (0.1, 0.5) p (float): Probability of applying the transform. Default: 0.5 Targets: image, volume Image types: uint8, float32 Number of channels: 3 Note: - This transform only works with RGB images. It will raise a TypeError if applied to non-RGB images. - The color shift is applied in the HSV color space, affecting the hue channel. - Luminance noise is added to all channels independently. - This transform can be useful for data augmentation in low-light scenarios or when training models to be robust against noisy inputs. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> transform = A.ISONoise(color_shift=(0.01, 0.05), intensity=(0.1, 0.5), p=0.5) >>> result = transform(image=image) >>> noisy_image = result["image"] References: ISO noise in digital photography: https://en.wikipedia.org/wiki/Image_noise#In_digital_cameras c*\rSrSr%S\S'S\S'Srg)ISONoise.InitSchemai r color_shiftjAnnotated[tuple[float, float], AfterValidator(check_range_bounds(0, None)), AfterValidator(nondecreasing)]rwruNrrurtrqr~r s    rtr~c8>[TU]US9 X lXlgr)rrrwr)rprrwrrs rqrISONoise.__init__ s 1"&rtc [U5 [R"UUU[RR U55$)aApply the ISONoise transform to the input image. Args: img (np.ndarray): The input image to apply the ISONoise transform to. color_shift (float): The color shift value. intensity (float): The intensity value. random_seed (int): The random seed. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied ISONoise transform. )r r iso_noiserrandom default_rng)rprrrw random_seedrs rqrISONoise.apply s:* c    II ! !+ .   rtcURRSS5nURR"UR6URR"UR 6US.$)aGenerate parameters dependent on the input data. Args: params (dict[str, Any]): Parameters from the previous transform. data (dict[str, Any]): Input data. Returns: dict[str, Any]: Dictionary with the following keys: - "color_shift" (float): The color shift value. - "intensity" (float): The intensity value. - "random_seed" (int): The random seed. r)rrwr)rrrrrrw)rprrrs rqr%ISONoise.get_params_dependent_on_data sW$++44Q B >>1143C3CD//@&  rt)rrw))rrrrr)rrrwrrr) rrrrrwrrrrrrwrrjrrs@rqr<r<W s.`  ,  ,8)3 '('''  ''           :       rtr<cn^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) r/i aApply Contrast Limited Adaptive Histogram Equalization (CLAHE) to the input image. CLAHE is an advanced method of improving the contrast in an image. Unlike regular histogram equalization, which operates on the entire image, CLAHE operates on small regions (tiles) in the image. This results in a more balanced equalization, preventing over-amplification of contrast in areas with initially low contrast. Args: clip_limit (tuple[float, float] | float): Controls the contrast enhancement limit. - If a single float is provided, the range will be (1, clip_limit). - If a tuple of two floats is provided, it defines the range for random selection. Higher values allow for more contrast enhancement, but may also increase noise. Default: (1, 4) tile_grid_size (tuple[int, int]): Defines the number of tiles in the row and column directions. Format is (rows, columns). Smaller tile sizes can lead to more localized enhancements, while larger sizes give results closer to global histogram equalization. Default: (8, 8) p (float): Probability of applying the transform. Default: 0.5 Notes: - Supports only RGB or grayscale images. - For color images, CLAHE is applied to the L channel in the LAB color space. - The clip limit determines the maximum slope of the cumulative histogram. A lower clip limit will result in more contrast limiting. - Tile grid size affects the adaptiveness of the method. More tiles increase local adaptiveness but can lead to an unnatural look if set too high. Targets: image, volume Image types: uint8, float32 Number of channels: 1, 3 Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> transform = A.CLAHE(clip_limit=(1, 4), tile_grid_size=(8, 8), p=1.0) >>> result = transform(image=image) >>> clahe_image = result["image"] References: - Tutorial: https://docs.opencv.org/master/d5/daf/tutorial_py_histogram_equalization.html - "Contrast Limited Adaptive Histogram Equalization.": https://ieeexplore.ieee.org/document/109340 c*\rSrSr%S\S'S\S'Srg)CLAHE.InitSchemai r" clip_limitzGAnnotated[tuple[int, int], AfterValidator(check_range_bounds(1, None))]tile_grid_sizeruNrrurtrqr~r s))__rtr~cN>[TU]US9 [SU5UlX lgr)rrr rr)rprrrrs rqrCLAHE.__init__ s* 14jA,rtc [U5(d[U5(d Sn[U5e[R"XUR 5$)aCApply the CLAHE transform to the input image. Args: img (np.ndarray): The input image to apply the CLAHE transform to. clip_limit (float): The contrast enhancement limit. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied CLAHE transform. z;CLAHE transformation expects 1-channel or 3-channel images.)rrrrclaher)rprrrr s rqr CLAHE.apply s@C  );C)@)@OCC. ||CT-@-@AArtcLSURR"UR60$)zGenerate parameters dependent on the input data. Returns: dict[str, float]: Dictionary with the following key: - "clip_limit" (float): The contrast enhancement limit. r)rrrros rqrCLAHE.get_params* s"dnn44dooFGGrt)rr)g@)r^r^r)rrrrrr)rrrrrrrwrrrrs@rqr/r/ s[2h`,` 36*0 -/-(-  --B$HHrtr/cf\rSrSrSrS SjrS SjrS SjrS SjrSSjr Sr g )r2i5 aRandomly rearrange channels of the image. Args: p (float): Probability of applying the transform. Default: 0.5. Targets: image Number of channels: Any Image types: uint8, float32 Examples: >>> import numpy as np >>> import albumentations as A >>> >>> # Create a sample image with distinct RGB channels >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> # Red channel (first channel) >>> image[:, :, 0] = np.linspace(0, 255, 100, dtype=np.uint8).reshape(1, 100) >>> # Green channel (second channel) >>> image[:, :, 1] = np.linspace(0, 255, 100, dtype=np.uint8).reshape(100, 1) >>> # Blue channel (third channel) - constant value >>> image[:, :, 2] = 128 >>> >>> # Apply channel shuffle transform >>> transform = A.ChannelShuffle(p=1.0) >>> result = transform(image=image) >>> shuffled_image = result['image'] >>> >>> # The channels have been randomly rearranged >>> # For example, the original order [R, G, B] might become [G, B, R] or [B, R, G] >>> # This results in a color shift while preserving all the original image data >>> # Note: For images with more than 3 channels, all channels are shuffled similarly c 8UcU$[R"X5$)aiApply the ChannelShuffle transform to the input image. Args: img (np.ndarray): The input image to apply the ChannelShuffle transform to. channels_shuffled (list[int] | None): The channels to shuffle. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied ChannelShuffle transform. )rchannel_shuffle)rprchannels_shuffledrs rqrChannelShuffle.apply] s "  $J%%c==rtc 8UcU$[R"X5$)aoApply the ChannelShuffle transform to the input images. Args: images (np.ndarray): The input images to apply the ChannelShuffle transform to. channels_shuffled (list[int] | None): The channels to shuffle. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The images with the applied ChannelShuffle transform. )rvolume_channel_shuffle)rprrrs rqrChannelShuffle.apply_to_imagesr s   $M,,VGGrtc 8UcU$[R"X5$)asApply the ChannelShuffle transform to the input volumes. Args: volumes (np.ndarray): The input volumes to apply the ChannelShuffle transform to. channels_shuffled (list[int] | None): The channels to shuffle. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The volumes with the applied ChannelShuffle transform. )rvolumes_channel_shuffle)rprrrs rqrChannelShuffle.apply_to_volumes s   $N--gIIrtc (UR"X40UD6$)aoApply the ChannelShuffle transform to the input volume. Args: volume (np.ndarray): The input volume to apply the ChannelShuffle transform to. channels_shuffled (list[int] | None): The channels to shuffle. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The volume with the applied ChannelShuffle transform. )r)rprrrs rqrChannelShuffle.apply_to_volume s##FHHHrtcUSn[U5S:Xd USS:XaSS0$[[US55nURR U5 SU0$)a7Generate parameters dependent on the input data. Args: params (dict[str, Any]): Parameters from the previous transform. data (dict[str, Any]): Input data. Returns: dict[str, Any]: Dictionary with the following key: - "channels_shuffled" (tuple[int, ...] | None): The channels to shuffle. rrrrN)rr2r+rshuffle)rprrrch_arrs rqr+ChannelShuffle.get_params_dependent_on_data s] w u:?eBi1n'. .eE"I&' v&#V,,rtruN)rrrlist[int] | Nonerrrwr)rrrrrrrwr)rrrrrrrwr)rrrrrrrwrrj) rxryrzr{rrrrrrr}rurtrqr2r25 sf%N> >,> >  >*H J I---  -rtr2c@\rSrSrSrS SjrS SjrS SjrS SjrSr g) r?i uRInvert the input image by subtracting pixel values from max values of the image types, i.e., 255 for uint8 and 1.0 for float32. Args: p (float): Probability of applying the transform. Default: 0.5. Targets: image, volume Image types: uint8, float32 Number of channels: Any Examples: >>> import numpy as np >>> import albumentations as A >>> import cv2 >>> >>> # Create a sample image with different elements >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> cv2.circle(image, (30, 30), 20, (255, 255, 255), -1) # White circle >>> cv2.rectangle(image, (60, 60), (90, 90), (128, 128, 128), -1) # Gray rectangle >>> >>> # Apply InvertImg transform >>> transform = A.InvertImg(p=1.0) >>> result = transform(image=image) >>> inverted_image = result['image'] >>> >>> # Result: >>> # - Black background becomes white (0 → 255) >>> # - White circle becomes black (255 → 0) >>> # - Gray rectangle is inverted (128 → 127) >>> # The same approach works for float32 images (0-1 range) and grayscale images c .[R"U5$)aApply the InvertImg transform to the input image. Args: img (np.ndarray): The input image to apply the InvertImg transform to. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied InvertImg transform. )rinvertrs rqrInvertImg.apply s}}S!!rtc.UR"U/UQ70UD6$)aaApply the InvertImg transform to the input images. Args: images (np.ndarray): The input images to apply the InvertImg transform to. *args (Any): Additional arguments (not used in this transform). **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The images with the applied InvertImg transform. rr]s rqrInvertImg.apply_to_images r`rtc.UR"U/UQ70UD6$)aeApply the InvertImg transform to the input volumes. Args: volumes (np.ndarray): The input volumes to apply the InvertImg transform to. *args (Any): Additional arguments (not used in this transform). **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The volumes with the applied InvertImg transform. rrbs rqrInvertImg.apply_to_volumes rdrtc.UR"U/UQ70UD6$)aaApply the InvertImg transform to the input volume. Args: volume (np.ndarray): The input volume to apply the InvertImg transform to. *args (Any): Additional arguments (not used in this transform). **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The volume with the applied InvertImg transform. rrfs rqrInvertImg.apply_to_volume r`rtruNrrmrnro) rxryrzr{rrrrrr}rurtrqr?r? s$L " 3 4 3rtr?c^\rSrSrSr"SS\5rS S U4SjjjrSSjrSSjr SSjr SS jr SS jr S r U=r$)rIi aP Applies random gamma correction to the input image. Gamma correction, or simply gamma, is a nonlinear operation used to encode and decode luminance or tristimulus values in imaging systems. This transform can adjust the brightness of an image while preserving the relative differences between darker and lighter areas, making it useful for simulating different lighting conditions or correcting for display characteristics. Args: gamma_limit (float | tuple[float, float]): If gamma_limit is a single float value, the range will be (1, gamma_limit). If it's a tuple of two floats, they will serve as the lower and upper bounds for gamma adjustment. Values are in terms of percentage change, e.g., (80, 120) means the gamma will be between 80% and 120% of the original. Default: (80, 120). eps (float): A small value added to the gamma to avoid division by zero or log of zero errors. Default: 1e-7. p (float): Probability of applying the transform. Default: 0.5. Targets: image, volume Image types: uint8, float32 Number of channels: Any Note: - The gamma correction is applied using the formula: output = input^gamma - Gamma values > 1 will make the image darker, while values < 1 will make it brighter - This transform is particularly useful for: * Simulating different lighting conditions * Correcting for non-linear display characteristics * Enhancing contrast in certain regions of the image * Data augmentation in computer vision tasks Mathematical Formulation: Let I be the input image and G (gamma) be the correction factor. The gamma correction is applied as follows: 1. Normalize the image to [0, 1] range: I_norm = I / 255 (for uint8 images) 2. Apply gamma correction: I_corrected = I_norm ^ (1 / G) 3. Scale back to original range: output = I_corrected * 255 (for uint8 images) The actual gamma value used is calculated as: G = 1 + (random_value / 100), where random_value is sampled from gamma_limit range. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) # Default usage >>> transform = A.RandomGamma(p=1.0) >>> augmented_image = transform(image=image)["image"] # Custom gamma range >>> transform = A.RandomGamma(gamma_limit=(50, 150), p=1.0) >>> augmented_image = transform(image=image)["image"] # Applying with other transforms >>> transform = A.Compose([ ... A.RandomGamma(gamma_limit=(80, 120), p=0.5), ... A.RandomBrightnessContrast(p=0.5), ... ]) >>> augmented_image = transform(image=image)["image"] References: - Gamma correction: https://en.wikipedia.org/wiki/Gamma_correction - Power law (Gamma) encoding: https://www.cambridgeincolour.com/tutorials/gamma-correction.htm c \rSrSr%S\S'Srg)RandomGamma.InitSchemai_ r" gamma_limitruNrrurtrqr~r_ s**rtr~cB>[TU]US9 [SU5Ulgr)rrr r)rprrrs rqrRandomGamma.__init__b s% 1 5{Crtc *[R"XS9$)aAApply the RandomGamma transform to the input image. Args: img (np.ndarray): The input image to apply the RandomGamma transform to. gamma (float): The gamma value. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied RandomGamma transform. gamma)rgamma_transform)rprrrs rqrRandomGamma.applyj s%%c77rtc  URXS9$)aGApply the RandomGamma transform to the input volume. Args: volume (np.ndarray): The input volume to apply the RandomGamma transform to. gamma (float): The gamma value. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The volume with the applied RandomGamma transform. rr)rprrrs rqrRandomGamma.apply_to_volumex zz&z..rtc  URXS9$)aKApply the RandomGamma transform to the input volumes. Args: volumes (np.ndarray): The input volumes to apply the RandomGamma transform to. gamma (float): The gamma value. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The volumes with the applied RandomGamma transform. rr)rprrrs rqrRandomGamma.apply_to_volumes szz'z//rtc  URXS9$)aGApply the RandomGamma transform to the input images. Args: images (np.ndarray): The input images to apply the RandomGamma transform to. gamma (float): The gamma value. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The images with the applied RandomGamma transform. rr)rprrrs rqrRandomGamma.apply_to_images rrtcRSURR"UR6S- 0$)aGenerate parameters dependent on the input data. Args: params (dict[str, Any]): Parameters from the previous transform. data (dict[str, Any]): Input data. Returns: dict[str, Any]: Dictionary with the following key: - "gamma" (float): The gamma value. rgY@)rrrrprrs rqr(RandomGamma.get_params_dependent_on_data s- T^^++T-=-=>F  rt)r))Pxr)rrrr)rrrrrrrwr)rrrrrrrwr)rrrrrrrwr)rrrrrrrwrrj)rxryrzr{rr(r~rrrrrrr}rrs@rqrIrI s]EN+,+ 4=D0D DD 8 / 0 /  rtrIcd^\rSrSrSr"SS\5rSS U4SjjjrS SjrSr U=r $) rWi aConvert an image to grayscale and optionally replicate the grayscale channel. This transform first converts a color image to a single-channel grayscale image using various methods, then replicates the grayscale channel if num_output_channels is greater than 1. Args: num_output_channels (int): The number of channels in the output image. If greater than 1, the grayscale channel will be replicated. Default: 3. method (Literal["weighted_average", "from_lab", "desaturation", "average", "max", "pca"]): The method used for grayscale conversion: - "weighted_average": Uses a weighted sum of RGB channels (0.299R + 0.587G + 0.114B). Works only with 3-channel images. Provides realistic results based on human perception. - "from_lab": Extracts the L channel from the LAB color space. Works only with 3-channel images. Gives perceptually uniform results. - "desaturation": Averages the maximum and minimum values across channels. Works with any number of channels. Fast but may not preserve perceived brightness well. - "average": Simple average of all channels. Works with any number of channels. Fast but may not give realistic results. - "max": Takes the maximum value across all channels. Works with any number of channels. Tends to produce brighter results. - "pca": Applies Principal Component Analysis to reduce channels. Works with any number of channels. Can preserve more information but is computationally intensive. p (float): Probability of applying the transform. Default: 0.5. Raises: TypeError: If the input image doesn't have 3 channels for methods that require it. Note: - The transform first converts the input image to single-channel grayscale, then replicates this channel if num_output_channels > 1. - "weighted_average" and "from_lab" are typically used in image processing and computer vision applications where accurate representation of human perception is important. - "desaturation" and "average" are often used in simple image manipulation tools or when computational speed is a priority. - "max" method can be useful in scenarios where preserving bright features is important, such as in some medical imaging applications. - "pca" might be used in advanced image analysis tasks or when dealing with hyperspectral images. Image types: uint8, float32 Returns: np.ndarray: Grayscale image with the specified number of channels. Examples: >>> import numpy as np >>> import albumentations as A >>> import cv2 >>> >>> # Create a sample color image with distinct RGB values >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> # Red square in top-left >>> image[10:40, 10:40, 0] = 200 >>> # Green square in top-right >>> image[10:40, 60:90, 1] = 200 >>> # Blue square in bottom-left >>> image[60:90, 10:40, 2] = 200 >>> # Yellow square in bottom-right (Red + Green) >>> image[60:90, 60:90, 0] = 200 >>> image[60:90, 60:90, 1] = 200 >>> >>> # Example 1: Default conversion (weighted average, 3 channels) >>> transform = A.ToGray(p=1.0) >>> result = transform(image=image) >>> gray_image = result['image'] >>> # Output has 3 duplicate channels with values based on RGB perception weights >>> # R=0.299, G=0.587, B=0.114 >>> assert gray_image.shape == (100, 100, 3) >>> assert np.allclose(gray_image[:, :, 0], gray_image[:, :, 1]) >>> assert np.allclose(gray_image[:, :, 1], gray_image[:, :, 2]) >>> >>> # Example 2: Single-channel output >>> transform = A.ToGray(num_output_channels=1, p=1.0) >>> result = transform(image=image) >>> gray_image = result['image'] >>> assert gray_image.shape == (100, 100, 1) >>> >>> # Example 3: Using different conversion methods >>> # "desaturation" method (min+max)/2 >>> transform_desaturate = A.ToGray( ... method="desaturation", ... p=1.0 ... ) >>> result = transform_desaturate(image=image) >>> gray_desaturate = result['image'] >>> >>> # "from_lab" method (using L channel from LAB colorspace) >>> transform_lab = A.ToGray( ... method="from_lab", ... p=1.0 >>> ) >>> result = transform_lab(image=image) >>> gray_lab = result['image'] >>> >>> # "average" method (simple average of channels) >>> transform_avg = A.ToGray( ... method="average", ... p=1.0 >>> ) >>> result = transform_avg(image=image) >>> gray_avg = result['image'] >>> >>> # "max" method (takes max value across channels) >>> transform_max = A.ToGray( ... method="max", ... p=1.0 >>> ) >>> result = transform_max(image=image) >>> gray_max = result['image'] >>> >>> # Example 4: Using grayscale in an augmentation pipeline >>> pipeline = A.Compose([ ... A.ToGray(p=0.5), # 50% chance of grayscale conversion ... A.RandomBrightnessContrast(p=1.0) # Always apply brightness/contrast ... ]) >>> result = pipeline(image=image) >>> augmented_image = result['image'] # May be grayscale or color >>> >>> # Example 5: Converting float32 image >>> float_image = image.astype(np.float32) / 255.0 # Range [0, 1] >>> transform = A.ToGray(p=1.0) >>> result = transform(image=float_image) >>> gray_float_image = result['image'] >>> assert gray_float_image.dtype == np.float32 >>> assert gray_float_image.max() <= 1.0 c8\rSrSr%\"SSS9rS\S'S\S'S rg ) ToGray.InitSchemai4 zThe number of output channels.r) descriptionrrnum_output_channelsPLiteral['weighted_average', 'from_lab', 'desaturation', 'average', 'max', 'pca']rruNrxryrzr{rrr|r}rurtrqr~r4 s$#(8$ S   rtr~c8>[TU]US9 XlX lgr)rrrr)rprrrrs rqrToGray.__init__B s  1#6  rtc  [U5(a[R"SSS9 U$[U5nU[:waUR S;a Sn[ U5e[R"XRUR 5$)aApply the ToGray transform to the input image. Args: img (np.ndarray): The input image to apply the ToGray transform to. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied ToGray transform. zThe image is already gray.r stacklevel>r-pcaaverage desaturationz/ToGray transformation expects 3-channel images.) rwarningswarnr r+rrrto_grayr)rprrrr s rqr ToGray.applyS st c " " MM61 EJ', + + D 1 DCC. ~~c#;#;T[[IIrt)rr)r[weighted_averager)rrrrrrr rxryrzr{rr(r~rrr}rrs@rqrWrW sV~@  ,  $%    "JJrtrWc^^\rSrSrSr"SS\5rSS U4SjjjrS SjrSr U=r $) rXip aConvert an input image from grayscale to RGB format. Args: num_output_channels (int): The number of channels in the output image. Default: 3. p (float): Probability of applying the transform. Default: 1.0. Targets: image, volume Image types: uint8, float32 Number of channels: 1 Note: - For single-channel (grayscale) images, the channel is replicated to create an RGB image. - If the input is already a 3-channel RGB image, it is returned unchanged. - This transform does not change the data type of the image (e.g., uint8 remains uint8). Raises: TypeError: If the input image has more than 1 channel. Examples: >>> import numpy as np >>> import albumentations as A >>> >>> # Convert a grayscale image to RGB >>> transform = A.Compose([A.ToRGB(p=1.0)]) >>> grayscale_image = np.random.randint(0, 256, (100, 100), dtype=np.uint8) >>> rgb_image = transform(image=grayscale_image)['image'] >>> assert rgb_image.shape == (100, 100, 3) c,\rSrSr%\"SS9rS\S'Srg)ToRGB.InitSchemai rrrrruNrrurtrqr~r s#(A;S.rtr~c,>[TU]US9 Xlgr)rrr)rprrrs rqrToRGB.__init__ s 1#6 rtc [U5(a+[R"SSS9 [R"U5$[ U5(d Sn[ U5e[R"UURS9$)a Apply the ToRGB transform to the input image. Args: img (np.ndarray): The input image to apply the ToRGB transform to. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied ToRGB transform. zThe image is already an RGB.rrzVToRGB transformation expects 2-dim images or 3-dim with the last dimension equal to 1.r) rrrrascontiguousarrayrrrgrayscale_to_multichannelrrprrr s rqr ToRGB.apply sh    MM8Q G'', ,!#&&jCC. //  $ 8 8  rtr)r[r)rrrrrrrs@rqrXrXp sD!F/,/ $%7 7 77  rtrXc>^\rSrSrSrSSU4SjjjrSSjrSrU=r$) rYi a" Apply a sepia filter to the input image. This transform converts a color image to a sepia tone, giving it a warm, brownish tint that is reminiscent of old photographs. The sepia effect is achieved by applying a specific color transformation matrix to the RGB channels of the input image. For grayscale images, the transform is a no-op and returns the original image. Args: p (float): Probability of applying the transform. Default: 0.5. Targets: image, volume Image types: uint8, float32 Number of channels: 1,3 Note: - The sepia effect only works with RGB images (3 channels). For grayscale images, the original image is returned unchanged since the sepia transformation would have no visible effect when R=G=B. - The sepia effect is created using a fixed color transformation matrix: [[0.393, 0.769, 0.189], [0.349, 0.686, 0.168], [0.272, 0.534, 0.131]] - The output image will have the same data type as the input image. - For float32 images, ensure the input values are in the range [0, 1]. Examples: >>> import numpy as np >>> import albumentations as A >>> # Apply sepia effect to a uint8 RGB image >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> transform = A.ToSepia(p=1.0) >>> sepia_image = transform(image=image)['image'] >>> assert sepia_image.shape == image.shape >>> assert sepia_image.dtype == np.uint8 >>> # Apply sepia effect to a float32 RGB image >>> image = np.random.rand(100, 100, 3).astype(np.float32) >>> transform = A.ToSepia(p=1.0) >>> sepia_image = transform(image=image)['image'] >>> assert sepia_image.shape == image.shape >>> assert sepia_image.dtype == np.float32 >>> assert 0 <= sepia_image.min() <= sepia_image.max() <= 1.0 >>> # No effect on grayscale images >>> gray_image = np.random.randint(0, 256, (100, 100), dtype=np.uint8) >>> transform = A.ToSepia(p=1.0) >>> result = transform(image=gray_image)['image'] >>> assert np.array_equal(result, gray_image) Mathematical Formulation: Given an input pixel [R, G, B], the sepia tone is calculated as: R_sepia = 0.393*R + 0.769*G + 0.189*B G_sepia = 0.349*R + 0.686*G + 0.168*B B_sepia = 0.272*R + 0.534*G + 0.131*B For grayscale images where R=G=B, this transformation would result in a simple scaling of the original value, so we skip it. The output values are clipped to the valid range for the image's data type. See Also: ToGray: For converting images to grayscale instead of sepia. ch>[TU]US9 [R"/SQ/SQ/SQ/5Ulg)Nr)gx&?gS㥛?gx&1?)gtV?gʡE?g/$?)g rh?gJ +?gS㥛?)rrrrsepia_transformation_matrix)rprrs rqrToSepia.__init__s0 1+-88 "$9;P Q, (rtc [U5(aU$[U5(d Sn[U5e[R"XR 5$)aApply the ToSepia transform to the input image. Args: img (np.ndarray): The input image to apply the ToSepia transform to. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied ToSepia transform. z5ToSepia transformation expects 1 or 3-channel images.)rrrrlinear_transformation_rgbrrs rqr ToSepia.applysE c " "JC  ICC. //5U5UVVrt)r)r)rrr) rxryrzr{rrrr}rrs@rqrYrY s EN  WWrtrYc*\rSrSr%S\S'S\S'Srg)InterpolationPydanticiLiteral[cv2.INTER_NEAREST, cv2.INTER_NEAREST_EXACT, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4, cv2.INTER_LINEAR_EXACT]upscale downscaleruNrrurtrqrrsrtrc^\rSrSrSr"SS\5rS\R\RS.S4S U4Sjjjr S S jr SS jr S r U=r $)r5i0a Decrease image quality by downscaling and upscaling back. This transform simulates the effect of a low-resolution image by first downscaling the image to a lower resolution and then upscaling it back to its original size. This process introduces loss of detail and can be used to simulate low-quality images or to test the robustness of models to different image resolutions. Args: scale_range (tuple[float, float]): Range for the downscaling factor. Should be two float values between 0 and 1, where the first value is less than or equal to the second. The actual downscaling factor will be randomly chosen from this range for each image. Lower values result in more aggressive downscaling. Default: (0.25, 0.25) interpolation_pair (dict[Literal["downscale", "upscale"], int]): A dictionary specifying the interpolation methods to use for downscaling and upscaling. Should contain two keys: - 'downscale': Interpolation method for downscaling - 'upscale': Interpolation method for upscaling Values should be OpenCV interpolation flags (e.g., cv2.INTER_NEAREST, cv2.INTER_LINEAR, etc.) Default: {'downscale': cv2.INTER_NEAREST, 'upscale': cv2.INTER_NEAREST} p (float): Probability of applying the transform. Should be in the range [0, 1]. Default: 0.5 Targets: image, volume Image types: uint8, float32 Note: - The actual downscaling factor is randomly chosen for each image from the range specified in scale_range. - Using different interpolation methods for downscaling and upscaling can produce various effects. For example, using INTER_NEAREST for both can create a pixelated look, while using INTER_LINEAR or INTER_CUBIC can produce smoother results. - This transform can be useful for data augmentation, especially when training models that need to be robust to variations in image quality or resolution. Examples: >>> import albumentations as A >>> import cv2 >>> transform = A.Downscale( ... scale_range=(0.5, 0.75), ... interpolation_pair={'downscale': cv2.INTER_NEAREST, 'upscale': cv2.INTER_LINEAR}, ... p=0.5 ... ) >>> transformed = transform(image=image) >>> downscaled_image = transformed['image'] c*\rSrSr%S\S'S\S'Srg)Downscale.InitSchemaifdict[Literal['downscale', 'upscale'], Literal[cv2.INTER_NEAREST, cv2.INTER_NEAREST_EXACT, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4, cv2.INTER_LINEAR_EXACT]]interpolation_pairr scale_rangeruNrrurtrqr~r fs    rtr~)rr)r r rc8>[TU]US9 XlX lgr)rrrr)rprrrrs rqrDownscale.__init__ys!" 1&"4rtc d[R"UUURSURSS9$)aBApply the Downscale transform to the input image. Args: img (np.ndarray): The input image to apply the Downscale transform to. scale (float): The downscaling factor. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied Downscale transform. r r )rdown_interpolationup_interpolation)rr r)rprrrs rqrDownscale.applys9 #66{C!44Y?   rtcLSURR"UR60$)zGenerate parameters dependent on the input data. Returns: dict[str, Any]: Dictionary with the following key: - "scale" (float): The downscaling factor. r)rrrros rqrDownscale.get_paramss$//1A1ABCCrt)rr)rrrrrr)rrrrrrrwrr4)rxryrzr{rr(r~cv2 INTER_NEARESTrrrr}rrs@rqr5r50sk3j , *,8))8I8I J5(5  5 55* &DDrtr5c^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) r@iaApply multiplicative noise to the input image. This transform multiplies each pixel in the image by a random value or array of values, effectively creating a noise pattern that scales with the image intensity. Args: multiplier (tuple[float, float]): The range for the random multiplier. Defines the range from which the multiplier is sampled. Default: (0.9, 1.1) per_channel (bool): If True, use a different random multiplier for each channel. If False, use the same multiplier for all channels. Setting this to False is slightly faster. Default: False elementwise (bool): If True, generates a unique multiplier for each pixel. If False, generates a single multiplier (or one per channel if per_channel=True). Default: False p (float): Probability of applying the transform. Default: 0.5 Targets: image, volume Image types: uint8, float32 Number of channels: Any Note: - When elementwise=False and per_channel=False, a single multiplier is applied to the entire image. - When elementwise=False and per_channel=True, each channel gets a different multiplier. - When elementwise=True and per_channel=False, each pixel gets the same multiplier across all channels. - When elementwise=True and per_channel=True, each pixel in each channel gets a unique multiplier. - Setting per_channel=False is slightly faster, especially for larger images. - This transform can be used to simulate various lighting conditions or to create noise that scales with image intensity. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> transform = A.MultiplicativeNoise(multiplier=(0.9, 1.1), per_channel=True, p=1.0) >>> result = transform(image=image) >>> noisy_image = result["image"] References: Multiplicative noise: https://en.wikipedia.org/wiki/Multiplicative_noise c4\rSrSr%S\S'S\S'S\S'Srg) MultiplicativeNoise.InitSchemair multiplierrr elementwiseruNrrurtrqr~rs  rtr~cZ>[TU]US9 [SU5UlX0lX lgr)rrr rrr)rprrrrrs rqrMultiplicativeNoise.__init__s0 14jA&&rtc [X5$)aqApply the MultiplicativeNoise transform to the input image. Args: img (np.ndarray): The input image to apply the MultiplicativeNoise transform to. multiplier (float | np.ndarray): The random multiplier. **kwargs (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied MultiplicativeNoise transform. )r)rprrkwargss rqrMultiplicativeNoise.applys"((rtcSU;aUSOUSSn[U5nUR(a2UR(a URO/URSSQSP7nOUR(aU4OSnURR UR SUR SU5R[R5nUR(dUS:a[R"XdSS 9nUR(d$UR(aURSSS5nURUR:waUR5nS U0$) Generate parameters dependent on the input data. Args: params (dict[str, Any]): The parameters of the transform. data (dict[str, Any]): The data to apply the transform to. Returns: dict[str, Any]: The parameters of the transform. rrrNrr)rrrr) r rrrrrrastyperrrepeatreshapesqueeze)rprrrrrrs rqr0MultiplicativeNoise.get_params_dependent_on_data s ")DW d8nQ6G'.   #'#3#3EKK9N5;;r?9NA9NE'+'7'7\OTE**22 OOA  OOA    &   L1$4:"EJD$4$4#++Aq"5J   u{{ *#++-Jj))rt)rrr))r@g?FFr)rrrrrrrr)rrrrr#rrwrrjrrs@rqr@r@s2h,3=!! '/ ' ' '  ' ') )') )  )&)*)*)*  )*)*rtr@c^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) r8i5aApply Fancy PCA augmentation to the input image. This augmentation technique applies PCA (Principal Component Analysis) to the image's color channels, then adds multiples of the principal components to the image, with magnitudes proportional to the corresponding eigenvalues times a random variable drawn from a Gaussian with mean 0 and standard deviation 'alpha'. Args: alpha (float): Standard deviation of the Gaussian distribution used to generate random noise for each principal component. Default: 0.1. p (float): Probability of applying the transform. Default: 0.5. Targets: image, volume Image types: uint8, float32 Number of channels: any Note: - This augmentation is particularly effective for RGB images but can work with any number of channels. - For grayscale images, it applies a simplified version of the augmentation. - The transform preserves the mean of the image while adjusting the color/intensity variation. - This implementation is based on the paper by Krizhevsky et al. and is similar to the one used in the original AlexNet paper. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> transform = A.FancyPCA(alpha=0.1, p=1.0) >>> result = transform(image=image) >>> augmented_image = result["image"] References: ImageNet Classification with Deep Convolutional Neural Networks: In Advances in Neural Information Processing Systems (Vol. 25). Curran Associates, Inc. c,\rSrSr%\"SS9rS\S'Srg)FancyPCA.InitSchemai`rrrrruN)rxryrzr{rrr|r}rurtrqr~r.`s{u"rtr~c,>[TU]US9 Xlgr)rrr)rprrrs rqrFancyPCA.__init__cs 1 rtc .[R"X5$)abApply the FancyPCA transform to the input image. Args: img (np.ndarray): The input image to apply the FancyPCA transform to. alpha_vector (np.ndarray): The random noise for each principal component. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied FancyPCA transform. )r fancy_pca)rpr alpha_vectorrs rqrFancyPCA.applyks"22rtcUSn[U5[:XaUSOSnURRSURU5R [ R5nSU0$)r&rrrrr3)rr rrrr'rr)rprrrrr3s rqr%FancyPCA.get_params_dependent_on_data~sbw$'J2N$NuRyTU ,,33Atzz<PWW JJ  --rt)rr)rrrr)rrr3rrrrwrrjrrs@rqr8r85s(T#,#  3 3!3 3  3&...  ..rtr8c^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) r4ia+ Randomly changes the brightness, contrast, saturation, and hue of an image. This transform is similar to torchvision's ColorJitter but with some differences due to the use of OpenCV instead of Pillow. The main differences are: 1. OpenCV and Pillow use different formulas to convert images to HSV format. 2. This implementation uses value saturation instead of uint8 overflow as in Pillow. These differences may result in slightly different output compared to torchvision's ColorJitter. Args: brightness (tuple[float, float] | float): How much to jitter brightness. If float: The brightness factor is chosen uniformly from [max(0, 1 - brightness), 1 + brightness]. If tuple: The brightness factor is sampled from the range specified. Should be non-negative numbers. Default: (0.8, 1.2) contrast (tuple[float, float] | float): How much to jitter contrast. If float: The contrast factor is chosen uniformly from [max(0, 1 - contrast), 1 + contrast]. If tuple: The contrast factor is sampled from the range specified. Should be non-negative numbers. Default: (0.8, 1.2) saturation (tuple[float, float] | float): How much to jitter saturation. If float: The saturation factor is chosen uniformly from [max(0, 1 - saturation), 1 + saturation]. If tuple: The saturation factor is sampled from the range specified. Should be non-negative numbers. Default: (0.8, 1.2) hue (float or tuple of float (min, max)): How much to jitter hue. If float: The hue factor is chosen uniformly from [-hue, hue]. Should have 0 <= hue <= 0.5. If tuple: The hue factor is sampled from the range specified. Values should be in range [-0.5, 0.5]. Default: (-0.5, 0.5) p (float): Probability of applying the transform. Should be in the range [0, 1]. Default: 0.5 Targets: image, volume Image types: uint8, float32 Number of channels: 1, 3 Note: - The order of application for these color transformations is random for each image. - The ranges for brightness, contrast, and saturation are applied as multiplicative factors. - The range for hue is applied as an additive factor. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> transform = A.ColorJitter(brightness=0.2, contrast=0.2, saturation=0.2, hue=0.1, p=1.0) >>> result = transform(image=image) >>> jittered_image = result['image'] References: - ColorJitter: https://pytorch.org/vision/stable/generated/torchvision.transforms.ColorJitter.html - Color Conversions: https://docs.opencv.org/3.4/de/d25/imgproc_color_conversions.html cz\rSrSr%S\S'S\S'S\S'S\S'\"SSSS5\S Sj55rSrg ) ColorJitter.InitSchemair brightnesscontrast saturationhuecURS:XaSnSnSnO!URS;aS[S54nSnSn[U[R5(a>US:a[ S URS 35eWU- nW(a [ US5nXdU-4nO@[U[5(a+[U5[:Xa[U/WQURP76 [S U5$) Nr=grrF)r:r;r<infrTzIf z- is a single number, it must be non negative.r) field_namerr&numbersNumberrnr-rrr,rr )r'valueinfoboundsbiasrlefts rq _check_ranges$ColorJitter.InitSchema._check_rangess%'"$LLE%L%0019$doo..[\e|tQ[TU]US9 [SU5Ul[SU5Ul[SU5Ul[SU5Ul[R[R[R[R/Ul gr) rrr r:r;r<r=radjust_brightness_torchvisionadjust_contrast_torchvisionadjust_saturation_torchvisionadjust_hue_torchvision transforms)rpr:r;r<r=rrs rqrColorJitter.__init__s 14jA2H= 4jA-s3  0 0  . .  0 0  ) )  rtchURR"UR6nURR"UR6nURR"UR6nURR"UR 6n/SQnUR RU5 UUUUUS.$)zsGenerate parameters for the ColorJitter transform. Returns: dict[str, Any]: The parameters of the transform. )rrrr[)r:r;r<r=order)rrr:r;r<r=rr)rpr:r;r<r=rSs rqrColorJitter.get_paramss^^++T__= >>))4==9^^++T__= nn$$dhh/ %%e,% $   rtc [U5(d[U5(d Sn[U5eX#XE/n UHn URU "XU 5nM U$)aApply the ColorJitter transform to the input image. Args: img (np.ndarray): The input image to apply the ColorJitter transform to. brightness (float): The brightness factor. contrast (float): The contrast factor. saturation (float): The saturation factor. hue (float): The hue factor. order (list[int]): The order of application for the color transformations. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied ColorJitter transform. zAColorJitter transformation expects 1-channel or 3-channel images.)rrrrP) rprr:r;r<r=rSrr color_transformsr(s rqrColorJitter.apply0s[2C  );C)@)@UCC. &*BA//!$S1*=>C rt)r:r;r=r<rP)g?g333333?rXrXr?r) r:rr;rr<rr=rrrr4)rrr:rr;rr<rr=rrSrrrrwr) rxryrzr{rr(r~rrrr}rrs@rqr4r4sGR"6,"6L3=0:2<+6  / . 0  )     , .              rtr4c^\rSrSrSr"SS\5r\"S5\S Sj55r S SU4Sjjjr \ SSj5r SS jr SS jrS rU=r$)rRiSu.Sharpen the input image using either kernel-based or Gaussian interpolation method. Implements two different approaches to image sharpening: 1. Traditional kernel-based method using Laplacian operator 2. Gaussian interpolation method (similar to Kornia's approach) Args: alpha (tuple[float, float]): Range for the visibility of sharpening effect. At 0, only the original image is visible, at 1.0 only its processed version is visible. Values should be in the range [0, 1]. Used in both methods. Default: (0.2, 0.5). lightness (tuple[float, float]): Range for the lightness of the sharpened image. Only used in 'kernel' method. Larger values create higher contrast. Values should be greater than 0. Default: (0.5, 1.0). method (Literal['kernel', 'gaussian']): Sharpening algorithm to use: - 'kernel': Traditional kernel-based sharpening using Laplacian operator - 'gaussian': Interpolation between Gaussian blurred and original image Default: 'kernel' kernel_size (int): Size of the Gaussian blur kernel for 'gaussian' method. Must be odd. Default: 5 sigma (float): Standard deviation for Gaussian kernel in 'gaussian' method. Default: 1.0 p (float): Probability of applying the transform. Default: 0.5. Image types: uint8, float32 Number of channels: Any Mathematical Formulation: 1. Kernel Method: The sharpening operation is based on the Laplacian operator L: L = [[-1, -1, -1], [-1, 8, -1], [-1, -1, -1]] The final kernel K is a weighted sum: K = (1 - a)I + a(L + λI) where: - a is the alpha value - λ is the lightness value - I is the identity kernel The output image O is computed as: O = K * I (convolution) 2. Gaussian Method: Based on the unsharp mask principle: O = aI + (1-a)G where: - I is the input image - G is the Gaussian blurred version of I - a is the alpha value (sharpness) The Gaussian kernel G(x,y) is defined as: G(x,y) = (1/(2πs²))exp(-(x²+y²)/(2s²)) Note: - Kernel sizes must be odd to maintain spatial alignment - Methods produce different visual results: * Kernel method: More pronounced edges, possible artifacts * Gaussian method: More natural look, limited to original sharpness Examples: >>> import albumentations as A >>> import numpy as np # Traditional kernel sharpening >>> transform = A.Sharpen( ... alpha=(0.2, 0.5), ... lightness=(0.5, 1.0), ... method='kernel', ... p=1.0 ... ) # Gaussian interpolation sharpening >>> transform = A.Sharpen( ... alpha=(0.5, 1.0), ... method='gaussian', ... kernel_size=5, ... sigma=1.0, ... p=1.0 ... ) References: - R. C. Gonzalez and R. E. Woods, "Digital Image Processing (4th Edition),": Chapter 3: Intensity Transformations and Spatial Filtering. - J. C. Russ, "The Image Processing Handbook (7th Edition),": Chapter 4: Image Enhancement. - T. Acharya and A. K. Ray, "Image Processing: Principles and Applications,": Chapter 5: Image Enhancement. - Unsharp masking: https://en.wikipedia.org/wiki/Unsharp_masking - Laplacian operator: https://en.wikipedia.org/wiki/Laplace_operator - Gaussian blur: https://en.wikipedia.org/wiki/Gaussian_blur See Also: - Blur: For Gaussian blurring - UnsharpMask: Alternative sharpening method - RandomBrightnessContrast: For adjusting image contrast c`\rSrSr%S\S'S\S'S\S'\"SS 9rS \S '\"S S 9rS\S'Srg)Sharpen.InitSchemaiHAnnotated[tuple[float, float], AfterValidator(check_range_bounds(0, 1))]rKAnnotated[tuple[float, float], AfterValidator(check_range_bounds(0, None))] lightnessLiteral['kernel', 'gaussian']rr[rr kernel_sizerrrrruN) rxryrzr{r|rr`rr}rurtrqr~r[s0WW^^-- A; S&{u"rtr~r`c"US-S:XaUS-$U$)Nrrrru)r'rDs rq_check_kernel_sizeSharpen._check_kernel_sizes"AINuqy55rtc\>[TU]US9 XlX lX0lX@lXPlgr)rrrr^rr`r)rprr^rr`rrrs rqrSharpen.__init__s/ 1 " & rtc[R"/SQ/SQ/SQ/[RS9n[R"/SQSSU-S//SQ/[RS9nSU- U-X--$)Nrrrrrrr)rrrrr^rrrr)rr^matrix_nochange matrix_effects rq__generate_sharpening_matrix$Sharpen.__generate_sharpening_matrixsb ((Iy)#DBJJW BI r2L A** E _,u/DDDrtcURR"UR6nURS:Xa8URR"UR6nUUR UU5S.$USS.$)zoGenerate parameters for the Sharpen transform. Returns: dict[str, Any]: The parameters of the transform. kernel)rsharpening_matrixN)rrrrr^$_Sharpen__generate_sharpening_matrix)rprr^s rqrSharpen.get_paramssn&& 3 ;;( "..?I%)%F%F& T::rtc URS:Xa[R"X5$[R"XURUR 5$)a$Apply the Sharpen transform to the input image. Args: img (np.ndarray): The input image to apply the Sharpen transform to. alpha (float): The alpha value. sharpening_matrix (np.ndarray | None): The sharpening matrix. **params (Any): Additional parameters for the transform. ro)rrconvolvesharpen_gaussianr`r)rprrrprs rqr Sharpen.applys> ;;( "??3: :&&s43C3CTZZPPrt)rr`r^rr)rDrrwr)rr)rrror(rr) rrr^rrr_r`rrrrr)rrr^rrwrr4) rrrrrpznp.ndarray | Nonerrrwr)rxryrzr{rr(r~rr+rbr staticmethodrqrrr}rrs@rqrRrRSs jX#,#]#6$6 &0)308"'.        E E E  E E;*Q QQ- Q  Q  QQrtrRc^\rSrSrSr"SS\5rS S U4Sjjjr\S Sj5r S Sjr SSjr S r U=r $)r6iaApply embossing effect to the input image. This transform creates an emboss effect by highlighting edges and creating a 3D-like texture in the image. It works by applying a specific convolution kernel to the image that emphasizes differences in adjacent pixel values. Args: alpha (tuple[float, float]): Range to choose the visibility of the embossed image. At 0, only the original image is visible, at 1.0 only its embossed version is visible. Values should be in the range [0, 1]. Alpha will be randomly selected from this range for each image. Default: (0.2, 0.5) strength (tuple[float, float]): Range to choose the strength of the embossing effect. Higher values create a more pronounced 3D effect. Values should be non-negative. Strength will be randomly selected from this range for each image. Default: (0.2, 0.7) p (float): Probability of applying the transform. Should be in the range [0, 1]. Default: 0.5 Targets: image, volume Image types: uint8, float32 Note: - The emboss effect is created using a 3x3 convolution kernel. - The 'alpha' parameter controls the blend between the original image and the embossed version. A higher alpha value will result in a more pronounced emboss effect. - The 'strength' parameter affects the intensity of the embossing. Higher strength values will create more contrast in the embossed areas, resulting in a stronger 3D-like effect. - This transform can be useful for creating artistic effects or for data augmentation in tasks where edge information is important. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> transform = A.Emboss(alpha=(0.2, 0.5), strength=(0.2, 0.7), p=0.5) >>> result = transform(image=image) >>> embossed_image = result['image'] References: - Image Embossing: https://en.wikipedia.org/wiki/Image_embossing - Application of Emboss Filtering in Image Processing: https://www.researchgate.net/publication/303412455_Application_of_Emboss_Filtering_in_Image_Processing c*\rSrSr%S\S'S\S'Srg)Emboss.InitSchemaiGr\rr]strengthruNrrurtrqr~r{GsWW]]rtr~c8>[TU]US9 XlX lgr)rrrr|)rprr|rrs rqrEmboss.__init__Ks 1  rtc[R"/SQ/SQ/SQ/[RS9n[R"SU- SU- S/SU- SSU-/SSU-SU-//[RS9nSU- U-X--$)Nrgrhrrrrri) alpha_samplestrength_samplerjrks rq__generate_emboss_matrixEmboss.__generate_emboss_matrixUs ((Iy)#DBJJWo%q?':A>_$a_)<=A'_)<=  **  L O3l6RRRrtcURR"UR6nURR"UR6nUR UUS9nSU0$)zuGenerate parameters for the Emboss transform. Returns: dict[str, np.ndarray]: The parameters of the transform. )rr emboss_matrix)rrrr|_Emboss__generate_emboss_matrix)rprr|rs rqrEmboss.get_paramses\&& 3>>))4==955$6  //rtc .[R"X5$)zApply the Emboss transform to the input image. Args: img (np.ndarray): The input image to apply the Emboss transform to. emboss_matrix (np.ndarray): The emboss matrix. **params (Any): Additional parameters for the transform. rrt)rprrrs rqr Emboss.applytss22rt)rr|)rw)rrhr)rrr|rrr)rrrrrwrrwrB)rrrrrrrwr)rxryrzr{rr(r~rrxrrrr}rrs@rqr6r6s1f^,^ &0(2 !"!&!  !! S  S# S  S S 03 3"3 3  33rtr6c^\rSrSrSr"SS\5rSSS\RS4S U4S jjjr SS jr SS jr S r U=r $)rViaTransform images partially/completely to their superpixel representation. Args: p_replace (tuple[float, float] | float): Defines for any segment the probability that the pixels within that segment are replaced by their average color (otherwise, the pixels are not changed). * A probability of ``0.0`` would mean, that the pixels in no segment are replaced by their average color (image is not changed at all). * A probability of ``0.5`` would mean, that around half of all segments are replaced by their average color. * A probability of ``1.0`` would mean, that all segments are replaced by their average color (resulting in a voronoi image). Behavior based on chosen data types for this parameter: * If a ``float``, then that ``float`` will always be used. * If ``tuple`` ``(a, b)``, then a random probability will be sampled from the interval ``[a, b]`` per image. Default: (0.1, 0.3) n_segments (tuple[int, int] | int): Rough target number of how many superpixels to generate. The algorithm may deviate from this number. Lower value will lead to coarser superpixels. Higher values are computationally more intensive and will hence lead to a slowdown. If tuple ``(a, b)``, then a value from the discrete interval ``[a..b]`` will be sampled per image. Default: (15, 120) max_size (int | None): Maximum image size at which the augmentation is performed. If the width or height of an image exceeds this value, it will be downscaled before the augmentation so that the longest side matches `max_size`. This is done to speed up the process. The final output image has the same size as the input image. Note that in case `p_replace` is below ``1.0``, the down-/upscaling will affect the not-replaced pixels too. Use ``None`` to apply no down-/upscaling. Default: 128 interpolation (OpenCV flag): Flag that is used to specify the interpolation algorithm. Should be one of: cv2.INTER_NEAREST, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4. Default: cv2.INTER_LINEAR. p (float): Probability of applying the transform. Default: 0.5. Targets: image, volume Image types: uint8, float32 Number of channels: Any Note: - This transform can significantly change the visual appearance of the image. - The transform makes use of a superpixel algorithm, which tends to be slow. If performance is a concern, consider using `max_size` to limit the image size. - The effect of this transform can vary greatly depending on the `p_replace` and `n_segments` parameters. - When `p_replace` is high, the image can become highly abstracted, resembling a voronoi diagram. - The transform preserves the original image type (uint8 or float32). Mathematical Formulation: 1. The image is segmented into approximately `n_segments` superpixels using the SLIC algorithm. 2. For each superpixel: - With probability `p_replace`, all pixels in the superpixel are replaced with their mean color. - With probability `1 - p_replace`, the superpixel is left unchanged. 3. If the image was resized due to `max_size`, it is resized back to its original dimensions. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) # Apply superpixels with default parameters >>> transform = A.Superpixels(p=1.0) >>> augmented_image = transform(image=image)['image'] # Apply superpixels with custom parameters >>> transform = A.Superpixels( ... p_replace=(0.5, 0.7), ... n_segments=(50, 100), ... max_size=None, ... interpolation=cv2.INTER_NEAREST, ... p=1.0 ... ) >>> augmented_image = transform(image=image)['image'] cJ\rSrSr%S\S'S\S'\"SS9rS\S 'S \S 'S rg )Superpixels.InitSchemair% p_replacer# n_segmentsrrrGmax_sizer interpolationruN)rxryrzr{r|rrr}rurtrqr~rs&##''${**  rtr~)rr)rrrc|>[TU]US9 [SU5Ul[SU5UlX0lX@lg)Nrrr)rrr rrrr)rprrrrrrs rqrSuperpixels.__init__s> 13Y?0*= *rtcURR"UR6nURR"UR6nUR R U5U:US.$)zsGenerate parameters for the Superpixels transform. Returns: dict[str, Any]: The parameters of the transform. )replace_samplesr)rrrrrrr)rprrs rqrSuperpixels.get_paramssZ^^++T__= NN " "DNN 3#44;;JG!K$  rtc ^[R"UUUURUR5$)aApply the Superpixels transform to the input image. Args: img (np.ndarray): The input image to apply the Superpixels transform to. replace_samples (Sequence[bool]): Whether to replace pixels in segments. n_segments (int): Number of superpixels. **kwargs (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied Superpixels transform. )r superpixelsrr)rprrrr#s rqrSuperpixels.applys0&!!    MM      rt)rrrr) rrrtuple[int, int] | intrrGrrrrr4) rrrzSequence[bool]rrr#rrwr)rxryrzr{rr(r~r INTER_LINEARrrrr}rrs@rqrVrVsWr  ,  2:,6"   +.+*+ +  + ++,    (        rtrVc^\rSrSrSr"SS\5rS\RS- \RS- 4S4S U4S jjjr SS jr SS jr S r U=r $)rPi-u Create ringing or overshoot artifacts by convolving the image with a 2D sinc filter. This transform simulates the ringing artifacts that can occur in digital image processing, particularly after sharpening or edge enhancement operations. It creates oscillations or overshoots near sharp transitions in the image. Args: blur_limit (tuple[int, int] | int): Maximum kernel size for the sinc filter. Must be an odd number in the range [3, inf). If a single int is provided, the kernel size will be randomly chosen from the range (3, blur_limit). If a tuple (min, max) is provided, the kernel size will be randomly chosen from the range (min, max). Default: (7, 15). cutoff (tuple[float, float]): Range to choose the cutoff frequency in radians. Values should be in the range (0, π). A lower cutoff frequency will result in more pronounced ringing effects. Default: (π/4, π/2). p (float): Probability of applying the transform. Default: 0.5. Targets: image, volume Image types: uint8, float32 Number of channels: Any Note: - Ringing artifacts are oscillations of the image intensity function in the neighborhood of sharp transitions, such as edges or object boundaries. - This transform uses a 2D sinc filter (also known as a 2D cardinal sine function) to introduce these artifacts. - The severity of the ringing effect is controlled by both the kernel size (blur_limit) and the cutoff frequency. - Larger kernel sizes and lower cutoff frequencies will generally produce more noticeable ringing effects. - This transform can be useful for: * Simulating imperfections in image processing or transmission systems * Testing the robustness of computer vision models to ringing artifacts * Creating artistic effects that emphasize edges and transitions in images Mathematical Formulation: The 2D sinc filter kernel is defined as: K(x, y) = cutoff * J₁(cutoff * √(x² + y²)) / (2π * √(x² + y²)) where: - J₁ is the Bessel function of the first kind of order 1 - cutoff is the chosen cutoff frequency - x and y are the distances from the kernel center The filtered image I' is obtained by convolving the input image I with the kernel K: I'(x, y) = ∑∑ I(x-u, y-v) * K(u, v) The convolution operation introduces the ringing artifacts near sharp transitions. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) # Apply ringing effect with default parameters >>> transform = A.RingingOvershoot(p=1.0) >>> ringing_image = transform(image=image)['image'] # Apply ringing effect with custom parameters >>> transform = A.RingingOvershoot( ... blur_limit=(9, 17), ... cutoff=(np.pi/6, np.pi/3), ... p=1.0 ... ) >>> ringing_image = transform(image=image)['image'] References: - Ringing artifacts: https://en.wikipedia.org/wiki/Ringing_artifacts - Sinc filter: https://en.wikipedia.org/wiki/Sinc_filter - Digital Image Processing: Rafael C. Gonzalez and Richard E. Woods, 4th Edition c*\rSrSr%S\S'S\S'Srg)RingingOvershoot.InitSchemair blur_limitzkAnnotated[tuple[float, float], AfterValidator(check_range_bounds(0, np.pi)), AfterValidator(nondecreasing)]cutoffruNrrurtrqr~rs))  rtr~)rgr[rrcN>[TU]US9 [SU5UlX lgNrr)rrr rr)rprrrrs rqrRingingOvershoot.__init__s) 10*= rtc>^^URRURSURSS-S5mTS-S:XaTS- mURR"UR6m[ R "SSS9 [ R"UU4SjTT/5nSSS5 TS-S[ R-- WTS- S-TS- S-4'UR[ R5[ R"U5- nS U0$!,(df  Nr=f) zGenerate parameters for the RingingOvershoot transform. Returns: dict[str, np.ndarray]: The parameters of the transform. rrrignore)divideinvalidc &>T[R"T[R"UTS- S- - S-UTS- S- - S--5-5-S[R-[R"UTS- S- - S-UTS- S- - S--5-- $)Nrr)rj1rrr)r:r;rksizes rq-RingingOvershoot.get_params..sV**RWWa519/&9a%?1PQ UVCV[\B\%\]]ruu9rwwUQY!O(;'AQ%RS)WXEX]^D^'^__ artNr[ro) r randrangerrrrerrstate fromfunctionrr'rsum)rprorrs @@rqrRingingOvershoot.get_paramss(();T__Q=ORS=SUVW 19> QJE''5[[( ;__a  F<6 threshold, else I. - Higher alpha values increase the strength of the sharpening effect. - Higher threshold values limit the sharpening effect to areas with more significant edges or details. - The blur_limit and sigma_limit parameters control the Gaussian blur used to create the mask. References: Unsharp Masking: https://en.wikipedia.org/wiki/Unsharp_masking Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> # Apply UnsharpMask with default parameters >>> transform = A.UnsharpMask(p=1.0) >>> sharpened_image = transform(image=image)['image'] >>> # Apply UnsharpMask with custom parameters >>> transform = A.UnsharpMask( ... blur_limit=(3, 7), ... sigma_limit=(0.1, 0.5), ... alpha=(0.2, 0.7), ... threshold=15, ... p=1.0 ... ) >>> sharpened_image = transform(image=image)['image'] c\rSrSr%S\S'S\S'\"SSS9rS \S 'S \S '\"S 5\SS j55r Sr g)UnsharpMask.InitSchemair! sigma_limitr%rrr)rorrrrc,[R"XSS9$)Nr[) min_value)fblurprocess_blur_limit)r'rDrEs rq _process_blur$UnsharpMask.InitSchema._process_blurs++E1E ErtruN)rDrrErrwr) rxryrzr{r|rrrr+rr}rurtrqr~rse..!, 3,))  &  F( F! F  F  ' Frtr~c>[TU]US9 [SU5Ul[SU5Ul[SU5UlX@lg)Nrrr)rrr rrrr)rprrrrrrs rqrUnsharpMask.__init__ sH 10*= 5{C/7 "rtcURRURSURSS-S5URR"UR6URR"UR 6S.$)zsGenerate parameters for the UnsharpMask transform. Returns: dict[str, Any]: The parameters of the transform. rrr)rrr)rrrrrrrs rqr(UnsharpMask.get_params_dependent_on_datasp^^--""Q& ^^++T-=-=>^^++TZZ8  rtc F[R"UUUUURS9$)aApply the UnsharpMask transform to the input image. Args: img (np.ndarray): The input image to apply the UnsharpMask transform to. ksize (int): The kernel size for the convolution. sigma (int): The standard deviation for the Gaussian blur. alpha (float): The visibility of the sharpened image. **params (Any): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied UnsharpMask transform. )rrr)r unsharp_maskr)rprrrrrs rqrUnsharpMask.apply-s**""  nn   rt)rrrr))r[rgrrwr r) rrrrrrrrrrrj) rrrrrrrrrrrwr rxryrzr{rr(r~rrrr}rrs@rqrZrZs<| F, F"-336-7 #) #1 #+ #  #  # #      *            rtrZc^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) rUiKaKApply spatter transform. It simulates corruption which can occlude a lens in the form of rain or mud. Args: mean (tuple[float, float] | float): Mean value of normal distribution for generating liquid layer. If single float mean will be sampled from `(0, mean)` If tuple of float mean will be sampled from range `(mean[0], mean[1])`. If you want constant value use (mean, mean). Default (0.65, 0.65) std (tuple[float, float] | float): Standard deviation value of normal distribution for generating liquid layer. If single float the number will be sampled from `(0, std)`. If tuple of float std will be sampled from range `(std[0], std[1])`. If you want constant value use (std, std). Default: (0.3, 0.3). gauss_sigma (tuple[float, float] | floats): Sigma value for gaussian filtering of liquid layer. If single float the number will be sampled from `(0, gauss_sigma)`. If tuple of float gauss_sigma will be sampled from range `(gauss_sigma[0], gauss_sigma[1])`. If you want constant value use (gauss_sigma, gauss_sigma). Default: (2, 3). cutout_threshold (tuple[float, float] | floats): Threshold for filtering liquid layer (determines number of drops). If single float it will used as cutout_threshold. If single float the number will be sampled from `(0, cutout_threshold)`. If tuple of float cutout_threshold will be sampled from range `(cutout_threshold[0], cutout_threshold[1])`. If you want constant value use `(cutout_threshold, cutout_threshold)`. Default: (0.68, 0.68). intensity (tuple[float, float] | floats): Intensity of corruption. If single float the number will be sampled from `(0, intensity)`. If tuple of float intensity will be sampled from range `(intensity[0], intensity[1])`. If you want constant value use `(intensity, intensity)`. Default: (0.6, 0.6). mode (Literal["rain", "mud"]): Type of corruption. Default: "rain". color (tuple[int, ...] | None): Corruption elements color. If list uses provided list as color for the effect. If None uses default colors based on mode (rain: (238, 238, 175), mud: (20, 42, 63)). p (float): probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 References: Benchmarking Neural Network Robustness to Common Corruptions and Perturbations: https://arxiv.org/abs/1903.12261 Examples: >>> import numpy as np >>> import albumentations as A >>> import cv2 >>> >>> # Create a sample image >>> image = np.ones((300, 300, 3), dtype=np.uint8) * 200 # Light gray background >>> # Add some gradient to make effects more visible >>> for i in range(300): ... image[i, :, :] = np.clip(image[i, :, :] - i // 3, 0, 255) >>> >>> # Example 1: Rain effect with default parameters >>> rain_transform = A.Spatter( ... mode="rain", ... p=1.0 ... ) >>> rain_result = rain_transform(image=image) >>> rain_image = rain_result['image'] # Image with rain drops >>> >>> # Example 2: Heavy rain with custom parameters >>> heavy_rain = A.Spatter( ... mode="rain", ... mean=(0.7, 0.7), # Higher mean = more coverage ... std=(0.2, 0.2), # Lower std = more uniform effect ... cutout_threshold=(0.65, 0.65), # Lower threshold = more drops ... intensity=(0.8, 0.8), # Higher intensity = more visible effect ... color=(200, 200, 255), # Blueish rain drops ... p=1.0 ... ) >>> heavy_rain_result = heavy_rain(image=image) >>> heavy_rain_image = heavy_rain_result['image'] >>> >>> # Example 3: Mud effect >>> mud_transform = A.Spatter( ... mode="mud", ... mean=(0.6, 0.6), ... std=(0.3, 0.3), ... cutout_threshold=(0.62, 0.62), ... intensity=(0.7, 0.7), ... p=1.0 ... ) >>> mud_result = mud_transform(image=image) >>> mud_image = mud_result['image'] # Image with mud splatters >>> >>> # Example 4: Custom colored mud >>> red_mud = A.Spatter( ... mode="mud", ... mean=(0.55, 0.55), ... std=(0.25, 0.25), ... cutout_threshold=(0.7, 0.7), ... intensity=(0.6, 0.6), ... color=(120, 40, 40), # Reddish-brown mud ... p=1.0 ... ) >>> red_mud_result = red_mud(image=image) >>> red_mud_image = red_mud_result['image'] >>> >>> # Example 5: Random effect (50% chance of applying) >>> random_spatter = A.Compose([ ... A.Spatter( ... mode="rain" if np.random.random() < 0.5 else "mud", ... p=0.5 ... ) ... ]) >>> random_result = random_spatter(image=image) >>> result_image = random_result['image'] # May or may not have spatter effect cx\rSrSr%S\S'S\S'S\S'S\S'S\S'S \S 'S \S '\"S S9SSj5rSrg)Spatter.InitSchemair%rcrdr! gauss_sigmacutout_thresholdrwLiteral['rain', 'mud']rkzSequence[int] | Nonecolorrirjc/SQ/SQS.nURcXRUlU$[UR5[:wa Sn[ U5eU$)N)r)r\*?)rainmudz6Color must be a list of three integers for RGB format.)rrkrr+rn)rpdefault_colorsr s rq _check_colorSpatter.InitSchema._check_colorsT'6lKNzz!+II6 KTZZ$44N o%Krt)rNrv)rxryrzr{r|rrr}rurtrqr~rsC ..**##$$## g &  ' rtr~c >[T U]US9 [SU5Ul[SU5Ul[SU5Ul[SU5Ul[SU5UlX`l[SU5Ul g)Nrrr) rrr rcrdrrrwrkr) rprcrdrrrwrkrrrs rqrSpatter.__init__sw 1.5 -s3 5{C $%:V #&&s7O< <!!#i'8&-HHrtc .USSSup4URR"UR6nURR"UR6nURR"UR6nURR"UR 6nUR n URR"UR6n [R"UR5S- n URRX44UUS9n [S[SU-5-S-5n [R "U U X4UU[R"S9 S XU:'U S :XaS S 0[$R&"XU S 9E$S S 0[$R("U U UUU URS9E$)zoGenerate parameters for the Spatter transform. Returns: dict[str, Any]: The parameters of the transform. rNrr)rarrr[r)srcdstrsigmaXsigmaY borderTyperrrk) liquid_layerrrwr)rrrrrwr)rrrcrdrrrkrwrrrrrrroundr GaussianBlurBORDER_REPLICATErget_rain_paramsget_mud_params)rprrr/r0rcrdrrrkrwrrrs rqr$Spatter.get_params_dependent_on_datasw+ ~~%%tyy1nn$$dhh/>>1143H3HI&&(8(89yyNN**DNN; $u,,,334 Aa%i((1,- .++  9: $445 6>((l[de  E  ##)!1#!%!6!6   rt)rrrrwrcrkrd))?r)rr)rr)(\?r)333333?rrNr)rcrrdrrrrrrwrrkrrztuple[int, ...] | Nonerr)rrrrrwrrjrrs@rqrUrUKsob,2-9+5398D1;'-(,4)4)41 4 6 4 / 4%4&4 44(I I!I  I,8 8 8   8 8 rtrUc^\rSrSrSr"SS\5rSSS\RS4SU4S jjjr SS jr SS jr \ SS j5r \ SS j5rSrU=r$)r3i9a Add lateral chromatic aberration by distorting the red and blue channels of the input image. Chromatic aberration is an optical effect that occurs when a lens fails to focus all colors to the same point. This transform simulates this effect by applying different radial distortions to the red and blue channels of the image, while leaving the green channel unchanged. Args: primary_distortion_limit (tuple[float, float] | float): Range of the primary radial distortion coefficient. If a single float value is provided, the range will be (-primary_distortion_limit, primary_distortion_limit). This parameter controls the distortion in the center of the image: - Positive values result in pincushion distortion (edges bend inward) - Negative values result in barrel distortion (edges bend outward) Default: (-0.02, 0.02). secondary_distortion_limit (tuple[float, float] | float): Range of the secondary radial distortion coefficient. If a single float value is provided, the range will be (-secondary_distortion_limit, secondary_distortion_limit). This parameter controls the distortion in the corners of the image: - Positive values enhance pincushion distortion - Negative values enhance barrel distortion Default: (-0.05, 0.05). mode (Literal["green_purple", "red_blue", "random"]): Type of color fringing to apply. Options are: - 'green_purple': Distorts red and blue channels in opposite directions, creating green-purple fringing. - 'red_blue': Distorts red and blue channels in the same direction, creating red-blue fringing. - 'random': Randomly chooses between 'green_purple' and 'red_blue' modes for each application. Default: 'green_purple'. interpolation (InterpolationType): Flag specifying the interpolation algorithm. Should be one of: cv2.INTER_NEAREST, cv2.INTER_LINEAR, cv2.INTER_CUBIC, cv2.INTER_AREA, cv2.INTER_LANCZOS4. Default: cv2.INTER_LINEAR. p (float): Probability of applying the transform. Should be in the range [0, 1]. Default: 0.5. Targets: image Image types: uint8, float32 Number of channels: 3 Note: - This transform only affects RGB images. Grayscale images will raise an error. - The strength of the effect depends on both primary and secondary distortion limits. - Higher absolute values for distortion limits will result in more pronounced chromatic aberration. - The 'green_purple' mode tends to produce more noticeable effects than 'red_blue'. Examples: >>> import albumentations as A >>> import cv2 >>> transform = A.ChromaticAberration( ... primary_distortion_limit=0.05, ... secondary_distortion_limit=0.1, ... mode='green_purple', ... interpolation=cv2.INTER_LINEAR, ... p=1.0 ... ) >>> transformed = transform(image=image) >>> aberrated_image = transformed['image'] References: Chromatic Aberration: https://en.wikipedia.org/wiki/Chromatic_aberration c>\rSrSr%S\S'S\S'S\S'S\S'S rg ) ChromaticAberration.InitSchemair$primary_distortion_limitsecondary_distortion_limit-Literal['green_purple', 'red_blue', 'random']rkrrruNrrurtrqr~rs"44$66;;  rtr~)g{Gzg{Gz?)gr green_purplerc|>[TU]US9 [SU5Ul[SU5UlX0lX@lgr)rrr rrrkr)rprrrkrrrs rqrChromaticAberration.__init__sJ 1(, ! $) %+/ ! &+ ' *rtc b[U5 [R"UUUUUUR5$)aApply the ChromaticAberration transform to the input image. Args: img (np.ndarray): The input image to apply the ChromaticAberration transform to. primary_distortion_red (float): The primary distortion coefficient for the red channel. secondary_distortion_red (float): The secondary distortion coefficient for the red channel. primary_distortion_blue (float): The primary distortion coefficient for the blue channel. secondary_distortion_blue (float): The secondary distortion coefficient for the blue channel. **params (dict[str, Any]): Additional parameters (not used in this transform). Returns: np.ndarray: The image with the applied ChromaticAberration transform. )r rchromatic_aberrationr)rprprimary_distortion_redsecondary_distortion_redprimary_distortion_bluesecondary_distortion_bluers rqrChromaticAberration.applys7. c**  " $ # %      rtc@URR"UR6nURR"UR6nURR"UR6nURR"UR6nUR UU5nUR UU5nUR S:Xa$UR UU5nUR UU5nUR S:Xa$UR UU5nUR UU5nUUUUS.$)z}Generate parameters for the ChromaticAberration transform. Returns: dict[str, float]: The parameters of the transform. rred_blue)rrrr)rrrr _match_signrk _unmatch_sign)rprrrrs rqrChromaticAberration.get_paramss>"&!7!79V9V!W#'>>#9#9  , ,$  #'.."8"8$:W:W"X$(NN$:$:  , ,% !$(#3#3 " $$  %)$4$4 # %% ! 99 &&*&6&6&'' #)-(8(8()) % 99 "&*&8&8&'' #)-(:(:()) % '=(@'>)B   rtcRUSs=:aU:dO USs=:a U:a U*$ U$U*$U$Nrruabs rqrChromaticAberration._match_signs8 IAI1q9192I%2Irtc<US:aUS:d US:a US:aU*$U$rrur s rqr!ChromaticAberration._unmatch_signs) Ea!eQ1q52Irt)rrkrr) rrrrrkrrrrr)rrrrrrrrrrrrrwrr)r rr rrwr)rxryrzr{rr(r~rrrrrrxrrr}rrs@rqr3r39sCJ  ,  ANBO>L   +"=+%@+< +  + ++8  !& #(  "'  $)     B3 j rtr3 blackbodyciedipr?)MAX_TEMPMIN_BLACKBODY_TEMP MIN_CIED_TEMP WHITE_TEMPSAMPLING_TEMP_PROBcx^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) rBia9Applies Planckian Jitter to the input image, simulating color temperature variations in illumination. This transform adjusts the color of an image to mimic the effect of different color temperatures of light sources, based on Planck's law of black body radiation. It can simulate the appearance of an image under various lighting conditions, from warm (reddish) to cool (bluish) color casts. PlanckianJitter vs. ColorJitter: PlanckianJitter is fundamentally different from ColorJitter in its approach and use cases: 1. Physics-based: PlanckianJitter is grounded in the physics of light, simulating real-world color temperature changes. ColorJitter applies arbitrary color adjustments. 2. Natural effects: This transform produces color shifts that correspond to natural lighting variations, making it ideal for outdoor scene simulation or color constancy problems. 3. Single parameter: Color changes are controlled by a single, physically meaningful parameter (color temperature), unlike ColorJitter's multiple abstract parameters. 4. Correlated changes: Color shifts are correlated across channels in a way that mimics natural light, whereas ColorJitter can make independent channel adjustments. When to use PlanckianJitter: - Simulating different times of day or lighting conditions in outdoor scenes - Augmenting data for computer vision tasks that need to be robust to natural lighting changes - Preparing synthetic data to better match real-world lighting variations - Color constancy research or applications - When you need physically plausible color variations rather than arbitrary color changes The logic behind PlanckianJitter: As the color temperature increases: 1. Lower temperatures (around 3000K) produce warm, reddish tones, simulating sunset or incandescent lighting. 2. Mid-range temperatures (around 5500K) correspond to daylight. 3. Higher temperatures (above 7000K) result in cool, bluish tones, similar to overcast sky or shade. This progression mimics the natural variation of sunlight throughout the day and in different weather conditions. Args: mode (Literal["blackbody", "cied"]): The mode of the transformation. - "blackbody": Simulates blackbody radiation color changes. - "cied": Uses the CIE D illuminant series for color temperature simulation. Default: "blackbody" temperature_limit (tuple[int, int] | None): The range of color temperatures (in Kelvin) to sample from. - For "blackbody" mode: Should be within [3000K, 15000K]. Default: (3000, 15000) - For "cied" mode: Should be within [4000K, 15000K]. Default: (4000, 15000) If None, the default ranges will be used based on the selected mode. Higher temperatures produce cooler (bluish) images, lower temperatures produce warmer (reddish) images. sampling_method (Literal["uniform", "gaussian"]): Method to sample the temperature. - "uniform": Samples uniformly across the specified range. - "gaussian": Samples from a Gaussian distribution centered at 6500K (approximate daylight). Default: "uniform" p (float): Probability of applying the transform. Default: 0.5 Targets: image Image types: uint8, float32 Number of channels: 3 Note: - The transform preserves the overall brightness of the image while shifting its color. - The "blackbody" mode provides a wider range of color shifts, especially in the lower (warmer) temperatures. - The "cied" mode is based on standard illuminants and may provide more realistic daylight variations. - The Gaussian sampling method tends to produce more subtle variations, as it's centered around daylight. - Unlike ColorJitter, this transform ensures that color changes are physically plausible and correlated across channels, maintaining the natural appearance of the scene under different lighting conditions. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) >>> transform = A.PlanckianJitter(mode="blackbody", ... temperature_range=(3000, 9000), ... sampling_method="uniform", ... p=1.0) >>> result = transform(image=image) >>> jittered_image = result["image"] References: - Planck's law: https://en.wikipedia.org/wiki/Planck%27s_law - CIE Standard Illuminants: https://en.wikipedia.org/wiki/Standard_illuminant - Color temperature: https://en.wikipedia.org/wiki/Color_temperature - Implementation inspired by: https://github.com/TheZino/PlanckianJitter cP\rSrSr%S\S'S\S'S\S'\"SS 9S S j5rS rg )PlanckianJitter.InitSchemaiqLiteral['blackbody', 'cied']rkz@Annotated[tuple[int, int], AfterValidator(nondecreasing)] | Nonetemperature_limitLiteral['uniform', 'gaussian']sampling_methodrirjc[[S5nURcVURS:Xa[[S5U4UlU$URS:Xa[[S5U4UlU$URS:XaD[ UR5[S:d[ UR5U:a [ S5eURS:XaD[ UR5[S:d[ UR5U:a [ S5eURS[S s=::aURS ::d O [ S 5eU$) NrrrrrzATemperature limits for blackbody should be in [3000, 15000] rangez[TU]US9 Xl[SU5UlX0lgr)rrrkr rr)rprkrrrrs rqrPlanckianJitter.__init__s1 1 !%&79J!K.rtc V[U5 [R"XURS9$)a Apply the PlanckianJitter transform to the input image. Args: img (np.ndarray): The input image to apply the PlanckianJitter transform to. temperature (int): The temperature to apply to the image. **params (Any): Additional parameters for the transform. rj)r rplanckian_jitterrk)rpr temperaturers rqrPlanckianJitter.applys# c&&sdiiHHrtc [Sn[SnURS:XasURR5U:a+URR UR SU5nGO'URR UUR S5nOURS:XaURR5U:a[[ R"URRS[ R"X R S- 5S- 55nX$- nOt[ R"URRS[ R"UR SU- 5S- 55nX$-nO[SUR35e[ R"UUR SUR S5nS [U50$) zwGenerate parameters for the PlanckianJitter transform. Returns: dict[str, Any]: The parameters of the transform. rrrrrrr[zUnknown sampling method: r&) rrrrrrrr gaussrnrr)rpsampling_prob_boundarysampling_temp_boundaryr&shifts rqrPlanckianJitter.get_paramss"77K!L!6|!D   9 ,~~$$&)??"nn44**1-* #nn44***1-  ! !Z /~~$$&)??NN((58N8Nq8QQRUVV 5< NN((t55a8;QQRUVV 5< 89M9M8NOP Pgg   " "1 %  " "1 % s;/00rt)rkrr)rNrr) rkrrztuple[int, int] | NonerrrrrwNone)rrr&rrrrwrr4rrs@rqrBrBspTl),)Z.948:C /* /2 /8 /  /  / / I4141rtrBc|^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) rSiaApply shot noise to the image by modeling photon counting as a Poisson process. Shot noise (also known as Poisson noise) occurs in imaging due to the quantum nature of light. When photons hit an imaging sensor, they arrive at random times following Poisson statistics. This transform simulates this physical process in linear light space by: 1. Converting to linear space (removing gamma) 2. Treating each pixel value as an expected photon count 3. Sampling actual photon counts from a Poisson distribution 4. Converting back to display space (reapplying gamma) The noise characteristics follow real camera behavior: - Noise variance equals signal mean in linear space (Poisson statistics) - Brighter regions have more absolute noise but less relative noise - Darker regions have less absolute noise but more relative noise - Noise is generated independently for each pixel and color channel Args: scale_range (tuple[float, float]): Range for sampling the noise scale factor. Represents the reciprocal of the expected photon count per unit intensity. Higher values mean more noise: - scale = 0.1: ~100 photons per unit intensity (low noise) - scale = 1.0: ~1 photon per unit intensity (moderate noise) - scale = 10.0: ~0.1 photons per unit intensity (high noise) Default: (0.1, 0.3) p (float): Probability of applying the transform. Default: 0.5 Targets: image Image types: uint8, float32 Note: - Performs calculations in linear light space (gamma = 2.2) - Preserves the image's mean intensity - Memory efficient with in-place operations - Thread-safe with independent random seeds Examples: >>> import numpy as np >>> import albumentations as A >>> # Generate synthetic image >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) >>> # Apply moderate shot noise >>> transform = A.ShotNoise(scale_range=(0.1, 1.0), p=1.0) >>> noisy_image = transform(image=image)["image"] References: - Shot noise: https://en.wikipedia.org/wiki/Shot_noise - Original paper: https://doi.org/10.1002/andp.19183622304 (Schottky, 1918) - Poisson process: https://en.wikipedia.org/wiki/Poisson_point_process - Gamma correction: https://en.wikipedia.org/wiki/Gamma_correction c \rSrSr%S\S'Srg)ShotNoise.InitSchemai$jAnnotated[tuple[float, float], AfterValidator(nondecreasing), AfterValidator(check_range_bounds(0, None))]rruNrrurtrqr~r1$s   rtr~c,>[TU]US9 Xlgr)rrr)rprrrs rqrShotNoise.__init__+s 1&rtc j[R"X[RR U55$)a+Apply the ShotNoise transform to the input image. Args: img (np.ndarray): The input image to apply the ShotNoise transform to. scale (float): The scale factor for the noise. random_seed (int): The random seed for the noise. **params (Any): Additional parameters for the transform. )r shot_noiserrr)rprrrrs rqrShotNoise.apply3s&   RYY-B-B;-OPPrtcURR"UR6URR SS5S.$)zqGenerate parameters for the ShotNoise transform. Returns: dict[str, Any]: The parameters of the transform. rr)rr)rrrrrros rqrShotNoise.get_paramsEs<^^++T-=-=>0099!YG  rt)r)rr)rrrr) rrrrrrrrrwrr4rrs@rqrSrSs5n , ,6'(' ''Q QQ Q  Q  Q$   rtrSc0\rSrSr%Sr\"SS9rS\S'Srg) NoiseParamsBaseiRz*Base class for all noise parameter models.forbid)extrastrrruN) rxryrzr{rr model_configr|r}rurtrqr;r;Rs4H-LOrtr;cb\rSrSr%SrS\S'\"SS9rS\S'\"SS S 9\ SS j55r S r g ) UniformParamsiYrzLiteral['uniform']rr) min_lengthlist[Sequence[float]]rangesrirjc/nUHkn[U5[:wa [S5eUupESUs=::a Us=::aS::d O [S5eUR[ U5[ U545 Mm U$)Nz%Each range must have exactly 2 valuesrrz.Range values must be in [-1, 1] and min <= max)rr,rnr,r)r'vr range_valuesmin_valmax_vals rqvalidate_rangesUniformParams.validate_ranges]srL< D( !HII+ G'1W11 !QRR MM5>5>: ;  rtruN)rFrCrwzlist[tuple[float, float]]) rxryrzr{rr|rrDrr+rJr}rurtrqrArAYs>%.J".$)Q$7F !7XG, - rtrAc8\rSrSr%SrS\S'S\S'S\S'S rg ) GaussianParamsikrzLiteral['gaussian']rUAnnotated[Sequence[float], AfterValidator(check_range_bounds(min_val=-1, max_val=1))]ruTAnnotated[Sequence[float], AfterValidator(check_range_bounds(min_val=0, max_val=1))]rtruNrxryrzr{rr|r}rurtrqrMrMks!&0J#0rtrMc8\rSrSr%SrS\S'S\S'S\S'S rg ) LaplaceParamsiwlaplacezLiteral['laplace']rrNrurOrruNrPrurtrqrRrRws!%.J".rtrRcB\rSrSr%SrS\S'S\S'S\S'S\S 'S rg ) BetaParamsirZzLiteral['beta']rzIAnnotated[Sequence[float], AfterValidator(check_range_bounds(min_val=0))] alpha_range beta_rangerOrruNrPrurtrqrUrUs*"(J(rtrUr) discriminatorc^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) r0iabApply random noise to image channels using various noise distributions. This transform generates noise using different probability distributions and applies it to image channels. The noise can be generated in three spatial modes and supports multiple noise distributions, each with configurable parameters. Args: noise_type(Literal["uniform", "gaussian", "laplace", "beta"]): Type of noise distribution to use. Options: - "uniform": Uniform distribution, good for simple random perturbations - "gaussian": Normal distribution, models natural random processes - "laplace": Similar to Gaussian but with heavier tails, good for outliers - "beta": Flexible bounded distribution, can be symmetric or skewed spatial_mode(Literal["constant", "per_pixel", "shared"]): How to generate and apply the noise. Options: - "constant": One noise value per channel, fastest - "per_pixel": Independent noise value for each pixel and channel, slowest - "shared": One noise map shared across all channels, medium speed approximation(float): float in [0, 1], default=1.0 Controls noise generation speed vs quality tradeoff. - 1.0: Generate full resolution noise (slowest, highest quality) - 0.5: Generate noise at half resolution and upsample - 0.25: Generate noise at quarter resolution and upsample Only affects 'per_pixel' and 'shared' spatial modes. noise_params(dict[str, Any] | None): Parameters for the chosen noise distribution. Must match the noise_type: uniform: ranges: list[tuple[float, float]] List of (min, max) ranges for each channel. Each range must be in [-1, 1]. If only one range is provided, it will be used for all channels. [(-0.2, 0.2)] # Same range for all channels [(-0.2, 0.2), (-0.1, 0.1), (-0.1, 0.1)] # Different ranges for RGB gaussian: mean_range: tuple[float, float], default (0.0, 0.0) Range for sampling mean value, in [-1, 1] std_range: tuple[float, float], default (0.1, 0.1) Range for sampling standard deviation, in [0, 1] laplace: mean_range: tuple[float, float], default (0.0, 0.0) Range for sampling location parameter, in [-1, 1] scale_range: tuple[float, float], default (0.1, 0.1) Range for sampling scale parameter, in [0, 1] beta: alpha_range: tuple[float, float], default (0.5, 1.5) Value < 1 = U-shaped, Value > 1 = Bell-shaped Range for sampling first shape parameter, in (0, inf) beta_range: tuple[float, float], default (0.5, 1.5) Value < 1 = U-shaped, Value > 1 = Bell-shaped Range for sampling second shape parameter, in (0, inf) scale_range: tuple[float, float], default (0.1, 0.3) Smaller scale for subtler noise Range for sampling output scale, in [0, 1] Examples: >>> # Constant RGB shift with different ranges per channel: >>> transform = AdditiveNoise( ... noise_type="uniform", ... spatial_mode="constant", ... noise_params={"ranges": [(-0.2, 0.2), (-0.1, 0.1), (-0.1, 0.1)]} ... ) Gaussian noise shared across channels: >>> transform = AdditiveNoise( ... noise_type="gaussian", ... spatial_mode="shared", ... noise_params={"mean_range": (0.0, 0.0), "std_range": (0.05, 0.15)} ... ) Note: Performance considerations: - "constant" mode is fastest as it generates only C values (C = number of channels) - "shared" mode generates HxW values and reuses them for all channels - "per_pixel" mode generates HxWxC values, slowest but most flexible Distribution characteristics: - uniform: Equal probability within range, good for simple perturbations - gaussian: Bell-shaped, symmetric, good for natural noise - laplace: Like gaussian but with heavier tails, good for outliers - beta: Very flexible shape, can be uniform, bell-shaped, or U-shaped Implementation details: - All noise is generated in normalized range and scaled by image max value - For uint8 images, final noise range is [-255, 255] - For float images, final noise range is [-1, 1] ch\rSrSr%S\S'S\S'S\S'\"SS S 9rS \S '\"S S9SSj5rSr g)AdditiveNoise.InitSchemai1Literal['uniform', 'gaussian', 'laplace', 'beta']r*Literal['constant', 'per_pixel', 'shared']rdict[str, Any] | None noise_paramsrrrorrrirjc"SS/0SSS.SSS.SSSS .S .nURb URO XRn0UES UR0En[[[[ S .URnU"S 0UD6nUR 5UlU$) NrD)grr)rg333333?r)rur)rg?r)rVrWr)rrrSrZrru)r_rrArMrRrU model_dump)rpdefault_params params_dict params_classvalidated_paramss rq_validate_noise_params/AdditiveNoise.InitSchema._validate_noise_paramss {m,6LQ*4\R#-",#- N04/@/@/L$++R`apapRqKI[H,HK)*("  oo L ,:k: !1 ; ; =D Krt)r_Nrv) rxryrzr{r|rrrrfr}rurtrqr~r[s<EE@@++$4 u4 g &#  '# rtr~cP>[TU]US9 XlX lX0lX@lgr)rrrrr_r)rprrr_rrrs rqrAdditiveNoise.__init__$s, 1$((*rtc .[R"X5$)a Apply the AdditiveNoise transform to the input image. Args: img (np.ndarray): The input image to apply the AdditiveNoise transform to. noise_map (np.ndarray): The noise map to apply to the image. **params (Any): Additional parameters for the transform. rzr|s rqrAdditiveNoise.apply2s//rtc SU;aUSOUSSn[URn[R"URUR UR URUURURS9nSU0$)zGenerate parameters for the AdditiveNoise transform. Args: params (dict[str, Any]): The parameters of the transform. data (dict[str, Any]): The data to apply the transform to. rrrrr}) r rrrrrrr_rr)rprrrrjr}s rqr*AdditiveNoise.get_params_dependent_on_dataBs~")DW d8nQ6G' 4 ))**++$$,,!22 Y''rt)rr_rr)rconstantNrr) rr\rr]r_r^rrrrrrjrrs@rqr0r0s\|*,*\IRCM.2" +E +A +, +  +  + +0 00 0  0 (((  ((rtr0c`^\rSrSrSr"SS\5rSSU4SjjjrSrU=r $) rFi^ag Randomly shift values for each channel of the input RGB image. A specialized version of AdditiveNoise that applies constant uniform shifts to RGB channels. Each channel (R,G,B) can have its own shift range specified. Args: r_shift_limit ((int, int) or int): Range for shifting the red channel. Options: - If tuple (min, max): Sample shift value from this range - If int: Sample shift value from (-r_shift_limit, r_shift_limit) - For uint8 images: Values represent absolute shifts in [0, 255] - For float images: Values represent relative shifts in [0, 1] Default: (-20, 20) g_shift_limit ((int, int) or int): Range for shifting the green channel. Options: - If tuple (min, max): Sample shift value from this range - If int: Sample shift value from (-g_shift_limit, g_shift_limit) - For uint8 images: Values represent absolute shifts in [0, 255] - For float images: Values represent relative shifts in [0, 1] Default: (-20, 20) b_shift_limit ((int, int) or int): Range for shifting the blue channel. Options: - If tuple (min, max): Sample shift value from this range - If int: Sample shift value from (-b_shift_limit, b_shift_limit) - For uint8 images: Values represent absolute shifts in [0, 255] - For float images: Values represent relative shifts in [0, 1] Default: (-20, 20) p (float): Probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 Note: - Values are shifted independently for each channel - For uint8 images: * Input ranges like (-20, 20) represent pixel value shifts * A shift of 20 means adding 20 to that channel * Final values are clipped to [0, 255] - For float32 images: * Input ranges like (-0.1, 0.1) represent relative shifts * A shift of 0.1 means adding 0.1 to that channel * Final values are clipped to [0, 1] Examples: >>> import numpy as np >>> import albumentations as A # Shift RGB channels of uint8 image >>> transform = A.RGBShift( ... r_shift_limit=30, # Will sample red shift from [-30, 30] ... g_shift_limit=(-20, 20), # Will sample green shift from [-20, 20] ... b_shift_limit=(-10, 10), # Will sample blue shift from [-10, 10] ... p=1.0 ... ) >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> shifted = transform(image=image)["image"] # Same effect using AdditiveNoise >>> transform = A.AdditiveNoise( ... noise_type="uniform", ... spatial_mode="constant", # One value per channel ... noise_params={ ... "ranges": [(-30/255, 30/255), (-20/255, 20/255), (-10/255, 10/255)] ... }, ... p=1.0 ... ) See Also: - AdditiveNoise: More general noise transform with various options: * Different noise distributions (uniform, gaussian, laplace, beta) * Spatial modes (constant, per-pixel, shared) * Approximation for faster computation - RandomToneCurve: For non-linear color transformations - RandomBrightnessContrast: For combined brightness and contrast adjustments - PlankianJitter: For color temperature adjustments - HueSaturationValue: For HSV color space adjustments - ColorJitter: For combined brightness, contrast, saturation adjustments c4\rSrSr%S\S'S\S'S\S'Srg)RGBShift.InitSchemair$ r_shift_limit g_shift_limit b_shift_limitruNrrurtrqr~rqs))))))rtr~c>SSjnU"[SU55U"[SU55U"[SU55/n[TU] SSSU0SUS9 [SU5Ul[SU5Ul[SU5Ulg) Nrcn[US5S:d[US5S:aUSS- USS- 4$U$)Nrrr)r )limits rqnormalize_range*RGBShift.__init__..normalize_rangesC58}q CaMA$5a5(%(U*:;;LrtrrnrDr)rrr_rr)rwrrwr)r rrrrrsrt)rprrrsrtrrxrDrs rqrRGBShift.__init__s  D!6 F G D!6 F G D!6 F G   #"F+  ""7G!"7G!"7Grt)rtrsrr)rrrr)rrrrsrrtrrr) rxryrzr{rr(r~rr}rrs@rqrFrF^s[Qf*,*6?5>5> H2 H3 H3 H  H HrtrFc^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) rQium Apply salt and pepper noise to the input image. Salt and pepper noise is a form of impulse noise that randomly sets pixels to either maximum value (salt) or minimum value (pepper). The amount and proportion of salt vs pepper noise can be controlled. The same noise mask is applied to all channels of the image to preserve color consistency. Args: amount ((float, float)): Range for total amount of noise (both salt and pepper). Values between 0 and 1. For example: - 0.05 means 5% of all pixels will be replaced with noise - (0.01, 0.06) will sample amount uniformly from 1% to 6% Default: (0.01, 0.06) salt_vs_pepper ((float, float)): Range for ratio of salt (white) vs pepper (black) noise. Values between 0 and 1. For example: - 0.5 means equal amounts of salt and pepper - 0.7 means 70% of noisy pixels will be salt, 30% pepper - (0.4, 0.6) will sample ratio uniformly from 40% to 60% Default: (0.4, 0.6) p (float): Probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 Note: - Salt noise sets pixels to maximum value (255 for uint8, 1.0 for float32) - Pepper noise sets pixels to 0 - The noise mask is generated once and applied to all channels to maintain color consistency (i.e., if a pixel is set to salt, all its color channels will be set to maximum value) - The exact number of affected pixels matches the specified amount as masks are generated without overlap Mathematical Formulation: For an input image I, the output O is: O[c,x,y] = max_value, if salt_mask[x,y] = True O[c,x,y] = 0, if pepper_mask[x,y] = True O[c,x,y] = I[c,x,y], otherwise where: - c is the channel index - salt_mask and pepper_mask are 2D boolean arrays applied to all channels - Number of True values in salt_mask = floor(H*W * amount * salt_ratio) - Number of True values in pepper_mask = floor(H*W * amount * (1 - salt_ratio)) - amount ∈ [amount_min, amount_max] - salt_ratio ∈ [salt_vs_pepper_min, salt_vs_pepper_max] Examples: >>> import albumentations as A >>> import numpy as np # Apply salt and pepper noise with default parameters >>> transform = A.SaltAndPepper(p=1.0) >>> noisy_image = transform(image=image)["image"] # Heavy noise with more salt than pepper >>> transform = A.SaltAndPepper( ... amount=(0.1, 0.2), # 10-20% of pixels will be noisy ... salt_vs_pepper=(0.7, 0.9), # 70-90% of noise will be salt ... p=1.0 ... ) >>> noisy_image = transform(image=image)["image"] References: - Digital Image Processing: Rafael C. Gonzalez and Richard E. Woods, 4th Edition, Chapter 5: Image Restoration and Reconstruction. - Fundamentals of Digital Image Processing: A. K. Jain, Chapter 7: Image Degradation and Restoration. - Salt and pepper noise: https://en.wikipedia.org/wiki/Salt-and-pepper_noise See Also: - GaussNoise: For additive Gaussian noise - MultiplicativeNoise: For multiplicative noise - ISONoise: For camera sensor noise simulation c*\rSrSr%S\S'S\S'Srg)SaltAndPepper.InitSchemai+r\amountsalt_vs_pepperruNrrurtrqr~r}+sXX``rtr~c8>[TU]US9 XlX lgr)rrr~r)rpr~rrrs rqrSaltAndPepper.__init__/s 1 ,rtcSU;aUSOUSSnURSSupEURR"UR6nURR"UR6nXE-n[ X-5n [ X-5n UR RXSS9n [R"U[S9n [R"U[S9n S XSU 'S XU S'U RXE5n U RXE5n U U S .$) zGenerate parameters for the SaltAndPepper transform. Args: params (dict[str, Any]): The parameters of the transform. data (dict[str, Any]): The data to apply the transform to. rrrNrF)rareplacerT) salt_mask pepper_mask) rrrr~rrrrrzerosrr))rprrrr/r0 total_amount salt_ratior num_pixelsnum_saltnoise_positionsrrs rqr*SaltAndPepper.get_params_dependent_on_data9s")DW d8nQ6G BQ ~~--t{{; ^^++T-@-@A ~,- z.///66tV[6\HHT. hht40 15 )8,-26 HI./%%f4 !))&8 #&  rtc 0[R"XU5$)aPApply the SaltAndPepper transform to the input image. Args: img (np.ndarray): The input image to apply the SaltAndPepper transform to. salt_mask (np.ndarray): The salt mask to apply to the image. pepper_mask (np.ndarray): The pepper mask to apply to the image. **params (Any): Additional parameters for the transform. )rapply_salt_and_pepper)rprrrrs rqrSaltAndPepper.applyds ++CKHHrt)r~r))rgQ?)r?rr)r~rrrrrrj) rrrrrrrrrwrrrs@rqrQrQsN`a,a '3.8 -#-,-  --) ) )   ) VI II I  I  IIrtrQc^\rSrSrSr"SS\5rSSU4SjjjrSSjrSSjr \ "SS S S S 9SS j5r \ "SS S S S 9SS j5r \ "SS S S S 9SSj5r SrU=r$)rCiwuApply plasma fractal pattern to modify image brightness and contrast. Uses Diamond-Square algorithm to generate organic-looking fractal patterns that create spatially-varying brightness and contrast adjustments. Args: brightness_range ((float, float)): Range for brightness adjustment strength. Values between -1 and 1: - Positive values increase brightness - Negative values decrease brightness - 0 means no brightness change Default: (-0.3, 0.3) contrast_range ((float, float)): Range for contrast adjustment strength. Values between -1 and 1: - Positive values increase contrast - Negative values decrease contrast - 0 means no contrast change Default: (-0.3, 0.3) plasma_size (int): Size of the initial plasma pattern grid. Larger values create more detailed patterns but are slower to compute. The pattern will be resized to match the input image dimensions. Default: 256 roughness (float): Controls how quickly the noise amplitude increases at each iteration. Must be greater than 0: - Low values (< 1.0): Smoother, more gradual pattern - Medium values (~2.0): Natural-looking pattern - High values (> 3.0): Very rough, noisy pattern Default: 3.0 p (float): Probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 Note: - Works with any number of channels (grayscale, RGB, multispectral) - The same plasma pattern is applied to all channels - Operations are performed in float32 precision - Final values are clipped to valid range [0, max_value] Mathematical Formulation: 1. Plasma Pattern Generation (Diamond-Square Algorithm): Starting with a 3x3 grid of random values in [-1, 1], iteratively: a) Diamond Step: For each 2x2 cell, compute center using diamond kernel: [[0.25, 0.0, 0.25], [0.0, 0.0, 0.0 ], [0.25, 0.0, 0.25]] b) Square Step: Fill remaining points using square kernel: [[0.0, 0.25, 0.0 ], [0.25, 0.0, 0.25], [0.0, 0.25, 0.0 ]] c) Add random noise scaled by roughness^iteration d) Normalize final pattern P to [0,1] range using min-max normalization 2. Brightness Adjustment: For each pixel (x,y): O(x,y) = I(x,y) + b·P(x,y) where: - I is the input image - b is the brightness factor - P is the normalized plasma pattern 3. Contrast Adjustment: For each pixel (x,y): O(x,y) = I(x,y)·(1 + c·P(x,y)) + μ·(1 - (1 + c·P(x,y))) where: - I is the input image - c is the contrast factor - P is the normalized plasma pattern - μ is the mean pixel value Examples: >>> import albumentations as A >>> import numpy as np # Default parameters >>> transform = A.PlasmaBrightnessContrast(p=1.0) # Custom adjustments >>> transform = A.PlasmaBrightnessContrast( ... brightness_range=(-0.5, 0.5), ... contrast_range=(-0.3, 0.3), ... plasma_size=512, # More detailed pattern ... roughness=0.7, # Smoother transitions ... p=1.0 ... ) References: - Fournier, Fussell, and Carpenter, "Computer rendering of stochastic models,": Communications of the ACM, 1982. Paper introducing the Diamond-Square algorithm. - Diamond-Square algorithm: https://en.wikipedia.org/wiki/Diamond-square_algorithm See Also: - RandomBrightnessContrast: For uniform brightness/contrast adjustments - CLAHE: For contrast limited adaptive histogram equalization - FancyPCA: For color-based contrast enhancement - HistogramMatching: For reference-based contrast adjustment cV\rSrSr%S\S'S\S'\"SS9rS\S'\"S S 9rS \S 'S rg)#PlasmaBrightnessContrast.InitSchemaizIAnnotated[tuple[float, float], AfterValidator(check_range_bounds(-1, 1))]brightness_rangecontrast_rangerrr plasma_sizerrr roughnessruN) rxryrzr{r|rrrr}rurtrqr~rs4    !A; S& A; 5&rtr~cP>[TU]US9 XlX lX0lX@lgr)rrrrrr)rprrrrrrs rqr!PlasmaBrightnessContrast.__init__s, 1 0,&"rtcUSnURR"UR6nURR"UR6n[R "USSUR URS9nUUUS.$)zGenerate parameters for the PlasmaBrightnessContrast transform. Args: params (dict[str, Any]): The parameters of the transform. data (dict[str, Any]): The data to apply the transform to. rNr target_shaperr)brightness_factorcontrast_factorplasma_pattern)rrrrrgenerate_plasma_patternrr)rprrrr:r;plasmas rqr5PlasmaBrightnessContrast.get_params_dependent_on_datasw^^++T-B-BC >>))4+>+>?//rnn!22 ",'$  rtc 4[R"UUUU5$)aApply the PlasmaBrightnessContrast transform to the input image. Args: img (np.ndarray): The input image to apply the PlasmaBrightnessContrast transform to. brightness_factor (float): The brightness factor to apply to the image. contrast_factor (float): The contrast factor to apply to the image. plasma_pattern (np.ndarray): The plasma pattern to apply to the image. **params (Any): Additional parameters for the transform. )r apply_plasma_brightness_contrast)rprrrrrs rqrPlasmaBrightnessContrast.applys#$66       rtspatialFTkeep_depth_dimrrc (UR"U40UD6$)zApply the PlasmaBrightnessContrast transform to a batch of images. Args: images (np.ndarray): The input images to apply the PlasmaBrightnessContrast transform to. **params (Any): Additional parameters for the transform. rrs rqr(PlasmaBrightnessContrast.apply_to_images7zz&+F++rtc (UR"U40UD6$)zApply the PlasmaBrightnessContrast transform to a volume. Args: volume (np.ndarray): The input volume to apply the PlasmaBrightnessContrast transform to. **params (Any): Additional parameters for the transform. rrs rqr(PlasmaBrightnessContrast.apply_to_volumeBrrtc (UR"U40UD6$)zApply the PlasmaBrightnessContrast transform to a batch of volumes. Args: volumes (np.ndarray): The input volumes to apply the PlasmaBrightnessContrast transform to. **params (Any): Additional parameters for the transform. rrs rqr)PlasmaBrightnessContrast.apply_to_volumesMzz',V,,rt)rrrr)g333333ӿrr@r) rrrrrrrrrrrj) rrrrrrrrrrrwrrrrrxryrzr{rr(r~rrrr rrrr}rrs@rqrCrCws%kZ ', '1<.9 #- #, # #  #  # #      >  !   #      2YuDX]^,_,Yt5X\],^,Yt4W[\-]-rtrCc^\rSrSrSr"SS\5rSSU4SjjjrSSjrSSjr \ "SS S S S 9SS j5r \ "SS S S S 9SS j5r \ "SS S S S 9SSj5r SrU=r$)rDiYa Apply plasma-based shadow effect to the image using Diamond-Square algorithm. Creates organic-looking shadows using plasma fractal noise pattern. The shadow intensity varies smoothly across the image, creating natural-looking darkening effects that can simulate shadows, shading, or lighting variations. Args: shadow_intensity_range (tuple[float, float]): Range for shadow intensity. Values between 0 and 1: - 0 means no shadow (original image) - 1 means maximum darkening (black) - Values between create partial shadows Default: (0.3, 0.7) roughness (float): Controls how quickly the noise amplitude increases at each iteration. Must be greater than 0: - Low values (< 1.0): Smoother, more gradual shadows - Medium values (~2.0): Natural-looking shadows - High values (> 3.0): Very rough, noisy shadows Default: 3.0 p (float): Probability of applying the transform. Default: 0.5. Targets: image Image types: uint8, float32 Note: - The transform darkens the image using a plasma pattern - Works with any number of channels (grayscale, RGB, multispectral) - Shadow pattern is generated using Diamond-Square algorithm with specific kernels - The same shadow pattern is applied to all channels - Final values are clipped to valid range [0, max_value] Mathematical Formulation: 1. Plasma Pattern Generation (Diamond-Square Algorithm): Starting with a 3x3 grid of random values in [-1, 1], iteratively: a) Diamond Step: For each 2x2 cell, compute center using diamond kernel: [[0.25, 0.0, 0.25], [0.0, 0.0, 0.0 ], [0.25, 0.0, 0.25]] b) Square Step: Fill remaining points using square kernel: [[0.0, 0.25, 0.0 ], [0.25, 0.0, 0.25], [0.0, 0.25, 0.0 ]] c) Add random noise scaled by roughness^iteration d) Normalize final pattern P to [0,1] range using min-max normalization 2. Shadow Application: For each pixel (x,y): O(x,y) = I(x,y) * (1 - i*P(x,y)) where: - I is the input image - P is the normalized plasma pattern - i is the sampled shadow intensity - O is the output image Examples: >>> import albumentations as A >>> import numpy as np # Default parameters for natural shadows >>> transform = A.PlasmaShadow(p=1.0) # Subtle, smooth shadows >>> transform = A.PlasmaShadow( ... shadow_intensity_range=(0.1, 0.3), ... roughness=0.7, ... p=1.0 ... ) # Dramatic, detailed shadows >>> transform = A.PlasmaShadow( ... shadow_intensity_range=(0.5, 0.9), ... roughness=0.3, ... p=1.0 ... ) References: - Fournier, Fussell, and Carpenter, "Computer rendering of stochastic models,": Communications of the ACM, 1982. Paper introducing the Diamond-Square algorithm. - Diamond-Square algorithm: https://en.wikipedia.org/wiki/Diamond-square_algorithm See Also: - PlasmaBrightnessContrast: For brightness/contrast adjustments using plasma patterns - RandomShadow: For geometric shadow effects - RandomToneCurve: For global lighting adjustments - PlasmaBrightnessContrast: For brightness/contrast adjustments using plasma patterns c6\rSrSr%S\S'\"SS9rS\S'Srg ) PlasmaShadow.InitSchemair\rrrrrruN)rxryrzr{r|rrr}rurtrqr~rs hh A; 5&rtr~cD>[TU]US9 XlX lX0lgr)rrrrr)rprrrrrs rqrPlasmaShadow.__init__s& 1&<#&"rtcUSnURR"UR6n[R"USSUR UR S9nUUS.$)zGenerate parameters for the PlasmaShadow transform. Args: params (dict[str, Any]): The parameters of the transform. data (dict[str, Any]): The data to apply the transform to. rNrr)rwr)rrrrrrr)rprrrrwrs rqr)PlasmaShadow.get_params_dependent_on_datasfwNN**D,G,GH //rnn!22 #$  rtc 0[R"XU5$)a]Apply the PlasmaShadow transform to the input image. Args: img (np.ndarray): The input image to apply the PlasmaShadow transform to. intensity (float): The intensity of the shadow to apply to the image. plasma_pattern (np.ndarray): The plasma pattern to apply to the image. **params (Any): Additional parameters for the transform. )rapply_plasma_shadow)rprrwrrs rqrPlasmaShadow.applys ))#.IIrtrFTrc (UR"U40UD6$)zApply the PlasmaShadow transform to a batch of images. Args: images (np.ndarray): The input images to apply the PlasmaShadow transform to. **params (Any): Additional parameters for the transform. rrs rqrPlasmaShadow.apply_to_imagesrrtc (UR"U40UD6$)zApply the PlasmaShadow transform to a batch of volume. Args: volume (np.ndarray): The input volume to apply the PlasmaShadow transform to. **params (Any): Additional parameters for the transform. rrs rqrPlasmaShadow.apply_to_volumerrtc (UR"U40UD6$)zApply the PlasmaShadow transform to a batch of volumes. Args: volumes (np.ndarray): The input volumes to apply the PlasmaShadow transform to. **params (Any): Additional parameters for the transform. rrs rqrPlasmaShadow.apply_to_volumesrrt)rrr))rrhrrr)rrrrrrrrrj) rrrwrrrrrrwrrrrrrs@rqrDrDYs^@',' 7A # 3 # # #  # #      :J JJ# J  J  J$YuDX]^,_,Yt5X\],^,Yt4W[\-]-rtrDc^\rSrSrSr"SS\5rS S U4SjjjrS SjrS Sjr Sr U=r $) r=iu>Apply various illumination effects to the image. This transform simulates different lighting conditions by applying controlled illumination patterns. It can create effects like: - Directional lighting (linear mode) - Corner shadows/highlights (corner mode) - Spotlights or local lighting (gaussian mode) These effects can be used to: - Simulate natural lighting variations - Add dramatic lighting effects - Create synthetic shadows or highlights - Augment training data with different lighting conditions Args: mode (Literal["linear", "corner", "gaussian"]): Type of illumination pattern: - 'linear': Creates a smooth gradient across the image, simulating directional lighting like sunlight through a window - 'corner': Applies gradient from any corner, simulating light source from a corner - 'gaussian': Creates a circular spotlight effect, simulating local light sources Default: 'linear' intensity_range (tuple[float, float]): Range for effect strength. Values between 0.01 and 0.2: - 0.01-0.05: Subtle lighting changes - 0.05-0.1: Moderate lighting effects - 0.1-0.2: Strong lighting effects Default: (0.01, 0.2) effect_type (str): Type of lighting change: - 'brighten': Only adds light (like a spotlight) - 'darken': Only removes light (like a shadow) - 'both': Randomly chooses between brightening and darkening Default: 'both' angle_range (tuple[float, float]): Range for gradient angle in degrees. Controls direction of linear gradient: - 0°: Left to right - 90°: Top to bottom - 180°: Right to left - 270°: Bottom to top Only used for 'linear' mode. Default: (0, 360) center_range (tuple[float, float]): Range for spotlight position. Values between 0 and 1 representing relative position: - (0, 0): Top-left corner - (1, 1): Bottom-right corner - (0.5, 0.5): Center of image Only used for 'gaussian' mode. Default: (0.1, 0.9) sigma_range (tuple[float, float]): Range for spotlight size. Values between 0.2 and 1.0: - 0.2: Small, focused spotlight - 0.5: Medium-sized light area - 1.0: Broad, soft lighting Only used for 'gaussian' mode. Default: (0.2, 1.0) p (float): Probability of applying the transform. Default: 0.5 Targets: image Image types: uint8, float32 Examples: >>> import albumentations as A >>> # Simulate sunlight through window >>> transform = A.Illumination( ... mode='linear', ... intensity_range=(0.05, 0.1), ... effect_type='brighten', ... angle_range=(30, 60) ... ) >>> >>> # Create dramatic corner shadow >>> transform = A.Illumination( ... mode='corner', ... intensity_range=(0.1, 0.2), ... effect_type='darken' ... ) >>> >>> # Add multiple spotlights >>> transform1 = A.Illumination( ... mode='gaussian', ... intensity_range=(0.05, 0.15), ... effect_type='brighten', ... center_range=(0.2, 0.4), ... sigma_range=(0.2, 0.3) ... ) >>> transform2 = A.Illumination( ... mode='gaussian', ... intensity_range=(0.05, 0.15), ... effect_type='darken', ... center_range=(0.6, 0.8), ... sigma_range=(0.3, 0.5) ... ) >>> transforms = A.Compose([transform1, transform2]) References: - Lighting in Computer Vision: https://en.wikipedia.org/wiki/Lighting_in_computer_vision - Image-based lighting: https://en.wikipedia.org/wiki/Image-based_lighting - Similar implementation in Kornia: https://kornia.readthedocs.io/en/latest/augmentation.html#randomlinearillumination - Research on lighting augmentation: "Learning Deep Representations of Fine-grained Visual Descriptions" https://arxiv.org/abs/1605.05395 - Photography lighting patterns: https://en.wikipedia.org/wiki/Lighting_pattern Note: - The transform preserves image range and dtype - Effects are applied multiplicatively to preserve texture - Can be combined with other transforms for complex lighting scenarios - Useful for training models to be robust to lighting variations cR\rSrSr%S\S'S\S'S\S'S\S 'S \S 'S \S 'Srg)Illumination.InitSchemai'Literal['linear', 'corner', 'gaussian']rkzMAnnotated[tuple[float, float], AfterValidator(check_range_bounds(0.01, 0.2))]intensity_range%Literal['brighten', 'darken', 'both'] effect_typezJAnnotated[tuple[float, float], AfterValidator(check_range_bounds(0, 360))]rr\ center_rangezLAnnotated[tuple[float, float], AfterValidator(check_range_bounds(0.2, 1.0))] sigma_rangeruNrrurtrqr~rs855  ;:      rtr~ch>[TU]US9 XlX lX0lX@lXPlX`lgr)rrrkrrrrr) rprkrrrrrrrs rqrIllumination.__init__s8 1 .&&(&rtcURR"UR6nSnURS:Xa#URR 5S:aSOSnOURS:XaSnX4-nUR S:Xa(URR"UR 6nUUS.$UR S:Xa!URRS S 5nUUS .$URR"UR6nURR"UR6nURR"UR6n UXx4U S .$) zGenerate parameters for the Illumination transform. Args: params (dict[str, Any]): The parameters of the transform. data (dict[str, Any]): The data to apply the transform to. rbothrrdarkenlinearrwrcornerrr[rwrrwr}r) rrrrrrkrrrr) rprrrwsignrrr:r;rs rqr)Illumination.get_params_dependent_on_datas8NN**D,@,@A    v %--/#512D    )D 99 NN**D,<,<=E&  99 ^^++Aq1F&   NN " "D$5$5 6 NN " "D$5$5 6&&(8(89"f  rtc URS:Xa[R"UUSUSS9$URS:Xa[R"UUSUSS9$[R"UUSUSUSS 9$) zApply the Illumination transform to the input image. Args: img (np.ndarray): The input image to apply the Illumination transform to. **params (Any): Additional parameters for the transform. rrwrrrrr}rr)rkrapply_linear_illuminationapply_corner_illuminationapply_gaussian_illuminationrs rqrIllumination.applys 99 33 -Wo  99 33 -h'  11 [)(#/   rt)rrrrrkr)r)rrr)rih)rr@)rrr)rkrrrrrrrrrrrrrrjrrrs@rqr=r=s@D , ,9A/:=C+3,6+5'5'-'; ' ) ' * ')' ''$' R  rtr=c^\rSrSrSr"SS\5rSSU4SjjjrSSjr\ "SSS S 9SS j5r \ "SS SS 9SS j5r \ "SSSS 9SS j5r Sr U=r$)r1i aAutomatically adjust image contrast by stretching the intensity range. This transform provides two methods for contrast enhancement: 1. CDF method (default): Uses cumulative distribution function for more gradual adjustment 2. PIL method: Uses linear scaling like PIL.ImageOps.autocontrast The transform can optionally exclude extreme values from both ends of the intensity range and preserve specific intensity values (e.g., alpha channel). Args: cutoff (float): Percentage of pixels to exclude from both ends of the histogram. Range: [0, 100]. Default: 0 (use full intensity range) - 0 means use the minimum and maximum intensity values found - 20 means exclude darkest and brightest 20% of pixels ignore (int, optional): Intensity value to preserve (e.g., alpha channel). Range: [0, 255]. Default: None - If specified, this intensity value will not be modified - Useful for images with alpha channel or special marker values method (Literal["cdf", "pil"]): Algorithm to use for contrast enhancement. Default: "cdf" - "cdf": Uses cumulative distribution for smoother adjustment - "pil": Uses linear scaling like PIL.ImageOps.autocontrast p (float): Probability of applying the transform. Default: 0.5 Targets: image Image types: uint8, float32 Note: - The transform processes each color channel independently - For grayscale images, only one channel is processed - The output maintains the same dtype as input - Empty or single-color channels remain unchanged Examples: >>> import albumentations as A >>> # Basic usage >>> transform = A.AutoContrast(p=1.0) >>> >>> # Exclude extreme values >>> transform = A.AutoContrast(cutoff=20, p=1.0) >>> >>> # Preserve alpha channel >>> transform = A.AutoContrast(ignore=255, p=1.0) >>> >>> # Use PIL-like contrast enhancement >>> transform = A.AutoContrast(method="pil", p=1.0) cP\rSrSr%\"SSS9rS\S'\"SSS9rS\S 'S \S 'S rg )AutoContrast.InitSchemai?rrrorrr)rGrLiteral['cdf', 'pil']rruN) rxryrzr{rrr|rr}rurtrqr~r?s*s++"aC0 0%%rtr~cD>[TU]US9 XlX lX0lgr)rrrrr)rprrrrrs rqrAutoContrast.__init__Ds$ 1   rtc n[R"XRURUR5$)zApply the AutoContrast transform to the input image. Args: img (np.ndarray): The input image to apply the AutoContrast transform to. **params (Any): Additional parameters for the transform. )r auto_contrastrrrrs rqrAutoContrast.applyPs%##Cdkk4;;OOrtrTFrc (UR"U40UD6$)zApply the AutoContrast transform to a batch of images. Args: images (np.ndarray): The input images to apply the AutoContrast transform to. **params (Any): Additional parameters for the transform. rrs rqrAutoContrast.apply_to_imagesZrrtc (UR"U40UD6$)zApply the AutoContrast transform to a batch of volumes. Args: volume (np.ndarray): The input volume to apply the AutoContrast transform to. **params (Any): Additional parameters for the transform. rrs rqrAutoContrast.apply_to_volumeerrtc (UR"U40UD6$)zApply the AutoContrast transform to a batch of volumes. Args: volumes (np.ndarray): The input volumes to apply the AutoContrast transform to. **params (Any): Additional parameters for the transform. rrs rqrAutoContrast.apply_to_volumesprrt)rrr)rNcdfr)rrrrGrrrrrrrrrrs@rqr1r1 s2h&,&!(-   &    PYd%H,I,Ye4H,I,Yd$G-H-rtr1c^\rSrSrSr"SS\5rSSU4SjjjrSSjrSSjr \ "S S SS 9SS j5r \ "S SS S 9SS j5r \ "S S S S 9SSj5r SSjrSrU=r$)r:i|a Applies H&E (Hematoxylin and Eosin) stain augmentation to histopathology images. This transform simulates different H&E staining conditions using either: 1. Predefined stain matrices (8 standard references) 2. Vahadane method for stain extraction 3. Macenko method for stain extraction 4. Custom stain matrices Args: method(Literal["preset", "random_preset", "vahadane", "macenko"]): Method to use for stain augmentation: - "preset": Use predefined stain matrices - "random_preset": Randomly select a preset matrix each time - "vahadane": Extract using Vahadane method - "macenko": Extract using Macenko method Default: "preset" preset(str | None): Preset stain matrix to use when method="preset": - "ruifrok": Standard reference from Ruifrok & Johnston - "macenko": Reference from Macenko's method - "standard": Typical bright-field microscopy - "high_contrast": Enhanced contrast - "h_heavy": Hematoxylin dominant - "e_heavy": Eosin dominant - "dark": Darker staining - "light": Lighter staining Default: "standard" intensity_scale_range(tuple[float, float]): Range for multiplicative stain intensity variation. Values are multipliers between 0.5 and 1.5. For example: - (0.7, 1.3) means stain intensities will vary from 70% to 130% - (0.9, 1.1) gives subtle variations - (0.5, 1.5) gives dramatic variations Default: (0.7, 1.3) intensity_shift_range(tuple[float, float]): Range for additive stain intensity variation. Values between -0.3 and 0.3. For example: - (-0.2, 0.2) means intensities will be shifted by -20% to +20% - (-0.1, 0.1) gives subtle shifts - (-0.3, 0.3) gives dramatic shifts Default: (-0.2, 0.2) augment_background(bool): Whether to apply augmentation to background regions. Default: False Targets: image Number of channels: 3 Image types: uint8, float32 References: - A. C. Ruifrok and D. A. Johnston, "Quantification of histochemical": Analytical and quantitative cytology and histology, 2001. - M. Macenko et al., "A method for normalizing histology slides for: 2009 IEEE International Symposium on quantitative analysis," 2009 IEEE International Symposium on Biomedical Imaging, 2009. Examples: >>> import numpy as np >>> import albumentations as A >>> import cv2 >>> >>> # Create a sample H&E stained histopathology image >>> # For real use cases, load an actual H&E stained image >>> image = np.zeros((300, 300, 3), dtype=np.uint8) >>> # Simulate tissue regions with different staining patterns >>> image[50:150, 50:150] = np.array([120, 140, 180], dtype=np.uint8) # Hematoxylin-rich region >>> image[150:250, 150:250] = np.array([140, 160, 120], dtype=np.uint8) # Eosin-rich region >>> >>> # Example 1: Using a specific preset stain matrix >>> transform = A.HEStain( ... method="preset", ... preset="standard", ... intensity_scale_range=(0.8, 1.2), ... intensity_shift_range=(-0.1, 0.1), ... augment_background=False, ... p=1.0 ... ) >>> result = transform(image=image) >>> transformed_image = result['image'] >>> >>> # Example 2: Using random preset selection >>> transform = A.HEStain( ... method="random_preset", ... intensity_scale_range=(0.7, 1.3), ... intensity_shift_range=(-0.15, 0.15), ... p=1.0 ... ) >>> result = transform(image=image) >>> transformed_image = result['image'] >>> >>> # Example 3: Using Vahadane method (requires H&E stained input) >>> transform = A.HEStain( ... method="vahadane", ... intensity_scale_range=(0.7, 1.3), ... p=1.0 ... ) >>> result = transform(image=image) >>> transformed_image = result['image'] >>> >>> # Example 4: Using Macenko method (requires H&E stained input) >>> transform = A.HEStain( ... method="macenko", ... intensity_scale_range=(0.7, 1.3), ... intensity_shift_range=(-0.2, 0.2), ... p=1.0 ... ) >>> result = transform(image=image) >>> transformed_image = result['image'] >>> >>> # Example 5: Combining with other transforms in a pipeline >>> transform = A.Compose([ ... A.HEStain(method="preset", preset="high_contrast", p=1.0), ... A.RandomBrightnessContrast(p=0.5), ... ]) >>> result = transform(image=image) >>> transformed_image = result['image'] cd\rSrSr%S\S'S\S'S\S'S\S 'S \S '\"S S 9SSj5rSrg)HEStain.InitSchemai9Literal['preset', 'random_preset', 'vahadane', 'macenko']rhLiteral['ruifrok', 'macenko', 'standard', 'high_contrast', 'h_heavy', 'e_heavy', 'dark', 'light'] | Nonepresetr2intensity_scale_rangezhAnnotated[tuple[float, float], AfterValidator(nondecreasing), AfterValidator(check_range_bounds(-1, 1))]intensity_shift_rangeraugment_backgroundrirjcURS:XaURc SUlU$URS:XaURb [S5eU$)Nrrm random_presetz:preset should not be specified when method='random_preset')rrrnros rq_validate_matrix_selection-HEStain.InitSchema._validate_matrix_selectionsM{{h&4;;+>( K/DKK4K !]^^Krt)rNrv)rxryrzr{r|rrr}rurtrqr~rsEII      ! g &  ' rtr~Fc>[TU]US9 XlX lX0lX@lXPlSUlUS;a%[R"[SU55Ul /SQUl g)Nr)vahadanemacenkozLiteral['vahadane', 'macenko'])ruifrokrrm high_contrasth_heavye_heavydarklight) rrrrrrrstain_normalizerrget_normalizerr stain_extractor preset_names)rprrrrrrrs rqrHEStain.__init__sl& 1  %:"%:""4 $ , ,#)#8#85v>$D   rtchURS:Xa*URb[RUR$URS:Xa8URR UR 5n[RU$URRU5 URR$)z*Get stain matrix based on selected method.rr) rrrSTAIN_MATRICESrrrrfitstain_matrix_target)rprrs rq_get_stain_matrixHEStain._get_stain_matrixFs ;;( "t{{'>((5 5 ;;/ ) NN11$2C2CDM((7 7   %##777rtc \[U5 [R"UUUUURS9$)aApply the HEStain transform to the input image. Args: img (np.ndarray): The input image to apply the HEStain transform to. stain_matrix (np.ndarray): The stain matrix to use for the transform. scale_factors (np.ndarray): The scale factors to use for the transform. shift_values (np.ndarray): The shift values to use for the transform. **params (Any): Additional parameters for the transform. )r stain_matrix scale_factors shift_valuesr)r rapply_he_stain_augmentationr)rprrrrrs rqr HEStain.applyQs4$ c11%'%#66   rtrTrc (UR"U40UD6$)zApply the HEStain transform to a batch of images. Args: images (np.ndarray): The input images to apply the HEStain transform to. **params (Any): Additional parameters for the transform. rrs rqrHEStain.apply_to_imageslrrtc (UR"U40UD6$)zApply the HEStain transform to a batch of volumes. Args: volume (np.ndarray): The input volumes to apply the HEStain transform to. **params (Any): Additional parameters for the transform. rrs rqrHEStain.apply_to_volumewrrtc (UR"U40UD6$)zApply the HEStain transform to a batch of volumes. Args: volumes (np.ndarray): The input volumes to apply the HEStain transform to. **params (Any): Additional parameters for the transform. rrs rqrHEStain.apply_to_volumesrrtcSU;aUSOUSSnURU5n[R"URR"UR 6URR"UR 6/5n[R"URR"UR 6URR"UR 6/5nUUUS.$)zGenerate parameters for the HEStain transform. Args: params (dict[str, Any]): The parameters of the transform. data (dict[str, Any]): The data to apply the transform to. rrr)rrr)r rrrrrr)rprrrrrrs rqr$HEStain.get_params_dependent_on_datas")DW d8nQ6G--e4 &&(B(BC&&(B(BC  xx&&(B(BC&&(B(BC  )*(  rt)rrrrrrrr)rN)rhg?rlFr) rrrrrrrrrrrr)rrrwr) rrrrrrrrrrrwrrrrrj)rxryrzr{rr(r~rr rr rrrrr}rrs@rqr:r:|sxt!,!JM\5?5@#(#* I*  *  3*  3* !!* " #* * X 8  ! "  !      6Yd%H,I,Ye4H,I,Yd$G-H-  rtr:)r __future__rrrBrcollections.abcrtypingrrrrr rXrnumpyrr r r r rrrrrpydanticrrrrrrrscipyrtyping_extensionsrr1albumentations.augmentations.geometric.functional augmentations geometricrr|!albumentations.augmentations.blurr,albumentations.augmentations.blur.transformsr"albumentations.augmentations.pixelr"albumentations.augmentations.utilsrr albumentations.core.pydanticr!r"r#r$r%r&r'(albumentations.core.transforms_interfacer(r)$albumentations.core.type_definitionsr*r+r,r-albumentations.core.utilsr.__all__NUM_BITS_ARRAY_LENGTHTWENTYrAr>rMrJrKrHrNrLrOr;rTrEr7rGr9r<r/r2r?rIrWrXrYrr5r@r8r4rRr6rVrPrZrUr3r-PLANCKIAN_COEFFSkeysr.rrBrSr;rArMrRrU NoiseParamsr0rFrQrCrDr=r1r:rurtrqr5sl# $88    +FFAGCI /- ^ n-"n-bm )m `h#hVI%IDV#VDD "D NV 'V r|L%|L~R2(R2jr +r jkL!kL\}D"}D@`)!`)FU 1U p{(#{(|{ !{ |]H ]H@@-'@-F\3"\3~Y $Y xzJ zJzE E P_W _WDI,yD"yDxF*,F*R].!].@{${|}Q }Q@o3 o3de $e PL,)L,^L $L ^k  k \R,Rl   - 2 2 4   ( - - /f55kBGGIJ008==?@ O1(O1dc "c LiO$ _  O     - BC %' B(&B(JyH}yHxZI&ZIz_-1_-D-%-Dl %l ^o-%o-dp  p rt