h# V%SrSSKJr SSKrSSKJr SSKJrJr SSK J r SSK r SSK r SSKJrJrJrJrJrJrJrJrJrJrJrJrJrJrJrJrJrJ r J!r!J"r"J#r#J$r$ SSK%J&s J's J(r) SSK*J+r+J,r, SS K-J.r.J/r/J0r0 \$\"SS j55r1\SS j5r2\$\SS j55r3SSS jjr4SSSjjr5SSjr6SSSjjr7\$\"SSSjj55r8\$SSj5r9\SSj5r:\$\"SSj55r;\$\"SSj55r<\$SSj5r=SSjr>\$SSj5r?\$\"SSj55r@SSjrA\$\\"SSj555rB\$\"\SSj555rC\$\SSj55rD\$\"SSj55rE\$\\"SSj555rFSS jrGSS!jrHSS"jrISS#jrJSS$jrK\\SS%j55rLSS&jrM\$\SS'j55rN\SS(j5rOSS)jrPSS*jrQ\SS+j5rRSS,jrSSSS-jjrT\"\$SS.j55rUSS/jrV\\\"SS0j555rW\"SS1j5rX\"SS2j5rY\\"SSS3jj55rZSS4jr[SS5jr\\$\"SS6j55r]\\\"SS7j555r^\"SS8j5r_\\\"SS9j555r`\\\"SS:j555ra\$\SS;j55rbSS<jrc0S=/S>Q_S?/S@Q_SA/SBQ_SC/SDQ_SE/SFQ_SG/SHQ_SI/SJQ_SK/SLQ_SM/SNQ_SO/SPQ_SQ/SRQ_SS/STQ_SU/SVQ_SW/SXQ_SY/SZQ_S[/S\Q_S]/S^Q_/S_Q/S`Q/SaQ/SbQ/ScQ/SdQ/SeQ/SfQSg.E0SA/ShQ_SC/SiQ_SE/SjQ_SG/SkQ_SI/SlQ_SK/SmQ_SM/SnQ_SO/SoQ_SQ/SpQ_SS/SqQ_SU/SrQ_SW/SsQ_SY/StQ_S[/SuQ_S]/SvQ_Sw/SxQ_Sy/SzQ_/S{Q/S|Q/S}Q/S~Q/SQ/SQS.ES.rdS\eS'\SSj5rf\SSj5rgSSSjjrh\"\SSj55riSSjrjSSjrkGSSjrlGSSjrmGSSjrnGSSjroGSSjrpGSSjrqGSSjrrGSSjrs\\"GSSj55rtGSSjru\ R"/SQ/SQ/SQ/\ RS9rx\ R"/SQ/SQ/SQ/\ RS9rySrzGSSjr{\\GSSj55r|\GSSj5r}GS Sjr~\GS Sj5r\GS Sj5r\GS Sj5r\$GS Sj5rGSSjrGSSjrGSSjrGSSjrGSSjrGSSjrGSSjrGSSjr\ R"/SQ/SQ/5\ R"/SQ/SQ/5\ R"/SQ/SQ/5\ R"/SQ/SQ/5\ R"/SQ/SQ/5\ R"/SQ/SQ/5\ R"/SQ/SQ/5\ R"/SQ/SQ/5S.rGSGSSjjrGSSjrGSSjr"SS5r"SS5rGSSjr"SS\5r"SS\5rGSSSjjr\\GSSj55r\\"GSSj55r\\"GSSj55rg(aFunctional implementations of image augmentation operations. This module contains low-level functions for various image augmentation techniques including color transformations, blur effects, tone curve adjustments, noise additions, and other visual modifications. These functions form the foundation for the transform classes and provide the core functionality for manipulating image data during the augmentation process. ) annotationsN)Sequence)AnyLiteral)warn)MAX_VALUES_BY_DTYPEadd add_array add_constant add_weightedclipclipped float32_io from_floatget_num_channelsis_grayscale_image is_rgb_imagemaybe_process_in_chunksmultiply multiply_addmultiply_by_arraymultiply_by_constantnormalize_per_imagepowerpreserve_channel_dimsz_lutuint8_io)PCA non_rgb_error)MONO_CHANNEL_DIMENSIONSNUM_MULTI_CHANNEL_DIMENSIONSNUM_RGB_CHANNELScDUS:XaUS:XaUS:XaU$[U5nU(a?US:wdUS:waSnSn[SSS9 [R"U[R5n[R"U[R 5n[R "U5upVnUS:wad[R"SS[RS9n[R"X-S5R[R5n[XXSS 9nUS:waUS:Hn [XbS S 9nSXi'US:wa [XsS S 9n[R"XVU45n[R"U[R 5nU(a%[R"U[R"5$U$) a6Shift the hue, saturation, and value of an image. Args: img (np.ndarray): The image to shift. hue_shift (float): The amount to shift the hue. sat_shift (float): The amount to shift the saturation. val_shift (float): The amount to shift the value. Returns: np.ndarray: The shifted image. rzqHueSaturationValue: hue_shift and sat_shift are not applicable to grayscale image. Set them to 0 or use RGB image) stackleveldtypeFinplaceT)rrcv2cvtColorCOLOR_GRAY2RGB COLOR_RGB2HSVsplitnparangeint16modastypeuint8rr merge COLOR_HSV2RGBCOLOR_RGB2GRAY) img hue_shift sat_shift val_shiftis_grayhuesatvallut_huegrayscale_masks g/var/www/fran/franai/venv/lib/python3.13/site-packages/albumentations/augmentations/pixel/functional.py shift_hsvrE7s](A~)q.Y!^  %G >Y!^II 1  ll3 2 23 ,,sC-- .CIIcNMCcA~))As"((3&&,c299"((CS51A~348 A~348 ))SsO $C ,,sC-- .C4;3<<S// 0DDcURn[UnU[R:Xa[R"[ [ U5S-5Vs/sHoDX-:aX4- OUPM snUS9nURn[XSS9n[U5UR:XaU$[R"US5$[R"X:X0- U5$s snf)aInvert all pixel values above a threshold. Args: img (np.ndarray): The image to solarize. Can be uint8 or float32. threshold (float): Normalized threshold value in range [0, 1]. For uint8 images: pixels above threshold * 255 are inverted For float32 images: pixels above threshold are inverted Returns: np.ndarray: Solarized image. Note: The threshold is normalized to [0, 1] range for both uint8 and float32 images. For uint8 images, the threshold is internally scaled by 255. r'Fr*) r(rr1r6arrayrangeintshaperlenndim expand_dimswhere)r: thresholdr(max_valilut prev_shapes rDsolarizerWws$ IIE!%(G hhEJ3w>> import numpy as np >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> # Same posterization for all channels >>> result = posterize(image, bits=3) >>> # Different posterization per channel >>> result = posterize(image, bits=[3, 4, 5]) # RGB channels rHrr&r'r$Fr*.T)r1r6rMrNr2r empty_like enumerate)r:bits bits_arrayrUmask result_imgrT channel_bitss rD posterizerasD$J   s:!3ii3bhh/q:~.233 c..s#J$Z0ii3bhh/q</01455 #CQKdC 36 1 rFc[R"U/S/US/S5R5n[R"UVs/sH o3(dM UPM sn5n[ U5S::aUR 5$[R"USS5S-nU(dUR 5$[R"[R"U5US--U-S5R[R5n[XSS 9$s snf) Nrr&rr&rHrIr$Tr*) r,calcHistravelr1rJrNcopysumminimumcumsumr5r6r)r:r^ histogram_fhsteprUs rD _equalize_pilros cUQCuh?EEGI y/yB"y/0A 1v{xxz 66!CR&>S D xxz **bii *TQY64? E L LRXX VC #D ))0s DDc Uc[R"U5$[R"U/S/US/S5R5n[R "U5(a[R "U5SOSn[R"U5nSXBU- - n[R"U5n[R"XfU- U-R5SS5R[R5n[XSS9$)Nrr&rcrdgo@Tr*)r, equalizeHistrerfr1any flatnonzerorhrjr roundr5r6r)r:r^rkrTtotalscalecumsum_histogramrUs rD _equalize_cvrxs |$$ cUQCuh?EEGI)+y(9(9y!!$sA FF9 E Uq\) *Eyy+ ''$'::eCJJLaQT U \ \]_]e]e fC #D ))rFcUbx[U5(a5[U5(a%[SURSUR35eU(d+[U5(dSUR3n[U5eggg)NzWrong mask shape. Image shape: z. Mask shape: zAWhen by_channels=False only 1-channel mask supports. Mask shape: )rr ValueErrorrM)r:r^ by_channelsmsgs rD_check_preconditionsr}s     "4S"9"91#))N4::,W #5d#;#;UVZV`V`UabCS/ !$<{ rFc~UcgUR[RSS9nUb[U5(dUSU4nU$)NF)rg.)r5r1r6r)r^rTs rD _handle_maskrsM | ;;    D  }/55CF| KrFc[XU5 US:Xa[O[n[U5(aU"U[ U55$U(db[ R "U[ R5nU"US[ U55US'[ R "U[ R5$[R"U5n[[5H!n[ X5nU"USU4U5USU4'M# U$)aApply histogram equalization to the input image. This function enhances the contrast of the input image by equalizing its histogram. It supports both grayscale and color images, and can operate on individual channels or on the luminance channel of the image. Args: img (np.ndarray): Input image. Can be grayscale (2D array) or RGB (3D array). mask (np.ndarray | None): Optional mask to apply the equalization selectively. If provided, must have the same shape as the input image. Default: None. mode (ImageMode): The backend to use for equalization. Can be either "cv" for OpenCV or "pil" for Pillow-style equalization. Default: "cv". by_channels (bool): If True, applies equalization to each channel independently. If False, converts the image to YCrCb color space and equalizes only the luminance channel. Only applicable to color images. Default: True. Returns: np.ndarray: Equalized image. The output has the same dtype as the input. Raises: ValueError: If the input image or mask have invalid shapes or types. Note: - If the input image is not uint8, it will be temporarily converted to uint8 for processing and then converted back to its original dtype. - For color images, when by_channels=False, the image is converted to YCrCb color space, equalized on the Y channel, and then converted back to RGB. - The function preserves the original number of channels in the image. Example: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> equalized = A.equalize(image, mode="cv", by_channels=True) >>> assert equalized.shape == image.shape >>> assert equalized.dtype == image.dtype pil.r.) r}rorxrrr,r-COLOR_RGB2YCrCbCOLOR_YCrCb2RGBr1rZrKr")r:r^moder{functionr_rT_masks rDequalizers\K0 $ }[ [R "U"X1U55[R SS9n[XSS9$[U[R5(a[U[R5(a[ [R "U"USS2[R4X5R5[R SS9n[R"[U5Vs/sH.n[USS2SS2U4[R"Xx5SS9PM0 sn5$[!S[#U5S [#U535es snf) a Rescales the relationship between bright and dark areas of the image by manipulating its tone curve. Args: img (np.ndarray): Any number of channels low_y (float | np.ndarray): per-channel or single y-position of a Bezier control point used to adjust the tone curve, must be in range [0, 1] high_y (float | np.ndarray): per-channel or single y-position of a Bezier control point used to adjust image tone curve, must be in range [0, 1] Returns: np.ndarray: Image with adjusted tone curve ?r&cXSU- nSUS--U-U-SU-US--U--US--S-$)NrHr$rd)tlow_yhigh_y one_minus_ts rD evaluate_bez%move_tone_curve..evaluate_bezgsO !e KN"Q&.[1a41G&1PPSTVWSWW[^^^rFFr*Nz?low_y and high_y must both be of type float or np.ndarray. Got z and )r np.ndarrayrfloat | np.ndarrayrrreturnr)r1linspacerisscalarr rintr6r isinstancendarraynewaxisTr,r7rKascontiguousarray TypeErrortype) r:rrrr num_channelsrUlutsrTs rDmove_tone_curverRsw& Cc"A_ _!_#_  _$C(L {{5bkk&11277<&9:BHHeTc..%$$FBJJ)G)G GGL1bjj=!15ACC D HH  yyY^_kYl mYlTUVC1aL""6"6tw"? OYl m    I$u+V[\`ag\h[ij  ns5F2c.[R"X5$)aApply a linear transformation to the RGB channels of an image. This function applies a linear transformation matrix to the RGB channels of an image. The transformation matrix is a 3x3 matrix that maps the RGB values to new values. Args: img (np.ndarray): Input image. Can be grayscale (2D array) or RGB (3D array). transformation_matrix (np.ndarray): 3x3 transformation matrix. Returns: np.ndarray: Image with the linear transformation applied. The output has the same dtype as the input. )r, transform)r:transformation_matrixs rDlinear_transformation_rgbrs$ == 44rFcJ[R"XS9n[U5(aURU5$[R"U[R 5nURUSS2SS2S45USS2SS2S4'[R"U[R 5$)aApply Contrast Limited Adaptive Histogram Equalization (CLAHE) to the input image. This function enhances the contrast of the input image using CLAHE. For color images, it converts the image to the LAB color space, applies CLAHE to the L channel, and then converts the image back to RGB. Args: img (np.ndarray): Input image. Can be grayscale (2D array) or RGB (3D array). clip_limit (float): Threshold for contrast limiting. Higher values give more contrast. tile_grid_size (tuple[int, int]): Size of grid for histogram equalization. Width and height of the grid. Returns: np.ndarray: Image with CLAHE applied. The output has the same dtype as the input. Note: - If the input image is float32, it's temporarily converted to uint8 for processing and then converted back to float32. - For color images, CLAHE is applied only to the luminance channel in the LAB color space. Raises: ValueError: If the input image is not 2D or 3D. Example: >>> import numpy as np >>> img = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8) >>> result = clahe(img, clip_limit=2.0, tile_grid_size=(8, 8)) >>> assert result.shape == img.shape >>> assert result.dtype == img.dtype ) clipLimit tileGridSizeNr)r, createCLAHErapplyr- COLOR_RGB2LAB COLOR_LAB2RGB)r: clip_limittile_grid_size clahe_matimg_labs rDclahers~L*RI#s##ll3 1 12G wq!Qw'78GAq!G <<!2!2 33rFc^^^ TS:Xa[RO[Rm [U5nS UUU 4SjjnUS:Xa,U"U[R5nUS[ R 4$US[4;a>US:Xa[ R"USSS9OUnU"U[R5nUSS U24$USS [24nU"U[R5n[[U5V s/sH1o"USU 4[R5S[ R 4PM3 n n [ R"U/U Q5$s sn f) a Compress the image using JPEG or WebP compression. Args: img (np.ndarray): Input image quality (int): Quality of compression in range [1, 100] image_type (Literal[".jpg", ".webp"]): Type of compression to use Returns: np.ndarray: Compressed image z.jpgcz>[R"TU[T5T45up#[R"X15$N)r,imencoderLimdecode)src_img read_mode_ encoded_img image_typequality quality_flags rD encode_decode(image_compression..encode_decodes0j'C >> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) >>> snowy_image = A.functional.add_snow_v1(image, snow_point=0.5, brightness_coeff=1.5) References: - HLS Color Space: https://en.wikipedia.org/wiki/HSL_and_HSV - Original implementation: https://github.com/UjjwalSaxena/Automold--Road-Augmentation-Library r$rNrHTr*) rr1r6r,r- COLOR_RGB2HLSr5float32r COLOR_HLS2RGB)r: snow_pointbrightness_coeff max_value image_hlslightness_channelr^s rDadd_snow_bleachrsj$BHH-I(1,Q?J S#"3"34I!!Q'*11"**=  )D//.$G+aAg << 3#4#4 55rFcURUSSSSS9n[R"USSSS9nURUSS5S :nX#4$) zGenerate snow texture and sparkle mask. Args: img_shape (tuple[int, int]): Image shape. random_generator (np.random.Generator): Random generator to use. Returns: tuple[np.ndarray, np.ndarray]: Tuple of (snow_texture, sparkle_mask) arrays. Nr$?g333333?)sizelocrvrrHsigmaXsigmaYGz?)normalr, GaussianBlurrandom) img_shaperandom_generator snow_texture sparkle_masks rDgenerate_snow_texturesrFs]$** "1 3c*RL##L&1ML$**9Ra=9D@L  %%rFcl[[Rn[R"U[R 5R [R5n[R"USS2SS2S4SX!---SU5USS2SS2S4'[R"USSSS9nURSn[R"SSU5SS2[R4nX8-n[R"U/S-5U-U-R [R5n [R"Xi5n [R"U S 5n [R "U S U S U-S5n [R"U R [R5[R"5n XUU/X'U $) aAdd a realistic snow effect to the input image. This function simulates snowfall by applying multiple visual effects to the image, including brightness adjustment, snow texture overlay, depth simulation, and color tinting. The result is a more natural-looking snow effect compared to simple pixel bleaching methods. Args: img (np.ndarray): Input image in RGB format. snow_point (float): Coefficient that controls the amount and intensity of snow. Should be in the range [0, 1], where 0 means no snow and 1 means maximum snow effect. brightness_coeff (float): Coefficient for brightness adjustment to simulate the reflective nature of snow. Should be in the range [0, 1], where higher values result in a brighter image. snow_texture (np.ndarray): Snow texture. sparkle_mask (np.ndarray): Sparkle mask. Returns: np.ndarray: Image with added snow effect. The output has the same dtype as the input. Note: - The function first converts the image to HSV color space for better control over brightness and color adjustments. - A snow texture is generated using Gaussian noise and then filtered for a more natural appearance. - A depth effect is simulated, with more snow at the top of the image and less at the bottom. - A slight blue tint is added to simulate the cool color of snow. - Random sparkle effects are added to simulate light reflecting off snow crystals. The snow effect is created through the following steps: 1. Brightness adjustment in HSV space 2. Generation of a snow texture using Gaussian noise 3. Application of a depth effect to the snow texture 4. Blending of the snow texture with the original image 5. Addition of a cool blue tint 6. Addition of sparkle effects Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) >>> snowy_image = A.functional.add_snow_v2(image, snow_coeff=0.5, brightness_coeff=0.2) Note: This function works with both uint8 and float32 image types, automatically handling the conversion between them. References: - Perlin Noise: https://en.wikipedia.org/wiki/Perlin_noise - HSV Color Space: https://en.wikipedia.org/wiki/HSL_and_HSV Nr$rHrrrg?r)333333??rH333333?333333?)rr1r6r,r-r/r5rr rrMrrrr full_like addWeightedr8) r:rrrrrimg_hsvrows depth_effect snow_layer img_with_snow blue_tints rDadd_snow_texturer^sxv$BHH-Ill3 1 1299"**EGww1aA 0 ==> GAq!G##L&1ML 99Q ??xxz ((*Cs"((3Jbhh(<'=>>J HHj-A 6EMM RXX  A~ *5:FGGC%$ ScK JrFc USSupE[S[[XE5S-U-55n[SUS-5n[U5Vs/sHoR Xv5PM sn$s snf)a\Generate radiuses for fog particles. Args: img_shape (tuple[int, int]): Image shape. num_particles (int): Number of fog particles. fog_intensity (float): Intensity of the fog effect, between 0 and 1. random_generator (np.random.Generator): Random generator to use. Returns: list[int]: List of radiuses for each fog particle. Nr$皙?rH)maxrLminrKintegers) r num_particles fog_intensityrheightwidthmax_fog_radius min_radiusrs rDget_fog_particle_radiusesr sk$bqMMFCF 2S 8= HIJNQ!+,JKPQ^K_ `K_a % %j AK_ `` `sA%c UR5n[X45HPuupgnUR5n [R"U Xg4USSS9 X!-n [R"XUSU - SUS9 MR [ S[ [URSS 5S -55n U S -S:XaU S- n [R"X[U 4S5n[U[RS S 9$) a<Add fog to an image. This function adds fog to an image by drawing fog particles on the image. The fog particles are drawn using the OpenCV function cv2.circle. Args: img (np.ndarray): The image to add fog to. fog_intensity (float): The intensity of the fog effect, between 0 and 1. alpha_coef (float): The coefficient for the alpha blending. fog_particle_positions (list[tuple[int, int]]): The positions of the fog particles. fog_particle_radiuses (list[int]): The radiuses of the fog particles. Returns: np.ndarray: The image with fog added. )rdrdrdrI)centerradiuscolor thicknessrHrrrNr$Tr*) rgzipr,circlerrrLrrMrr r1r6) r:r alpha_coeffog_particle_positionsfog_particle_radiusesresultxyr overlayalpha blur_sizes rDadd_fogr/&s4XXZF4L++- 6!  * E 1&IMAs3syy!}-345I1}Q   f)&un uppXyU -- nX- n[R"XZU 4XS5 [XYUSU - 5nM@ UV s/sHn [ U 5PM nn UR5nUS-nXx- S-n[ R "S[US5US9n [ R "SX/S9n[U5HYn[R"X^[ UU5US5 XU- S- XU- S- -XU- S- -n[UUUSU- 5nM[ U$s sn f)am Add a sun flare effect to an image using a simple overlay technique. This function creates a basic sun flare effect by overlaying multiple semi-transparent circles of varying sizes and intensities on the input image. The effect simulates a simple lens flare caused by bright light sources. Args: img (np.ndarray): The input image. flare_center (tuple[float, float]): (x, y) coordinates of the flare center in pixel coordinates. src_radius (int): The radius of the main sun circle in pixels. src_color (tuple[int, ...]): The color of the sun, represented as a tuple of RGB values. circles (list[Any]): A list of tuples, each representing a circle that contributes to the flare effect. Each tuple contains: - alpha (float): The transparency of the circle (0.0 to 1.0). - center (tuple[int, int]): (x, y) coordinates of the circle center. - radius (int): The radius of the circle. - color (tuple[int, int, int]): RGB color of the circle. Returns: np.ndarray: The output image with the sun flare effect added. Note: - This function uses a simple alpha blending technique to overlay flare elements. - The main sun is created as a gradient circle, fading from the center outwards. - Additional flare circles are added along an imaginary line from the sun's position. - This method is computationally efficient but may produce less realistic results compared to more advanced techniques. The flare effect is created through the following steps: 1. Create an overlay image and output image as copies of the input. 2. Add smaller flare circles to the overlay. 3. Blend the overlay with the output image using alpha compositing. 4. Add the main sun circle with a radial gradient. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [100, 100, 3], dtype=np.uint8) >>> flare_center = (50, 50) >>> src_radius = 20 >>> src_color = (255, 255, 200) >>> circles = [ ... (0.1, (60, 60), 5, (255, 200, 200)), ... (0.2, (70, 70), 3, (200, 255, 200)) ... ] >>> flared_image = A.functional.add_sun_flare_overlay( ... image, flare_center, src_radius, src_color, circles ... ) References: - Alpha compositing: https://en.wikipedia.org/wiki/Alpha_compositing - Lens flare: https://en.wikipedia.org/wiki/Lens_flare rrIrH r)num) rgr,r%r rLr1rrrK)r: flare_center src_radius src_colorcirclesr,outputweighted_brightnesstotal_radius_lengthr-r*r+rad3 circle_colorpoint num_times max_alpharadrTalps rDadd_sun_flare_overlayrB[s[BhhjG XXZF-4)vtt|+# 7FD;gfa%i@ .5 * *\SV\E *kkmGb I $9A=I KKSC0i @E ++a 3C 9  73s1v; 2>MA%&1}q/@)AAEVW-Z[J[D\\gsFAG< M% +s-D?c UR5nURSSupg[R"U[RS9n[ R "XX#S5 SHn [US[R"[R"U 55[Xv5--5[US[R"[R"U 55[Xv5--54n [ R"XXS5 M UH+upp[ R "X[U S-5US5 M- [ R"US S S S 9n[RSU2SU24unn[R"UUS- S-XS- S--5nS[R "U[Xv5S -- SS5- n[R""U/S -5nUU-n[%[ R&"U55n[ R"USS S S S 9US'[ R"USS SSS 9US'[ R("U5nSSU- SU- -S- - $)a1 Add a more realistic sun flare effect to the image. This function creates a complex sun flare effect by simulating various optical phenomena that occur in real camera lenses when capturing bright light sources. The result is a more realistic and physically plausible lens flare effect. Args: img (np.ndarray): Input image. flare_center (tuple[int, int]): (x, y) coordinates of the sun's center in pixels. src_radius (int): Radius of the main sun circle in pixels. src_color (tuple[int, int, int]): Color of the sun in RGB format. circles (list[Any]): List of tuples, each representing a flare circle with parameters: (alpha, center, size, color) - alpha (float): Transparency of the circle (0.0 to 1.0). - center (tuple[int, int]): (x, y) coordinates of the circle center. - size (float): Size factor for the circle radius. - color (tuple[int, int, int]): RGB color of the circle. Returns: np.ndarray: Image with added sun flare effect. Note: This function implements several techniques to create a more realistic flare: 1. Separate flare layer: Allows for complex manipulations of the flare effect. 2. Lens diffraction spikes: Simulates light diffraction in camera aperture. 3. Radial gradient mask: Creates natural fading of the flare from the center. 4. Gaussian blur: Softens the flare for a more natural glow effect. 5. Chromatic aberration: Simulates color fringing often seen in real lens flares. 6. Screen blending: Provides a more realistic blending of the flare with the image. The flare effect is created through the following steps: 1. Create a separate flare layer. 2. Add the main sun circle and diffraction spikes to the flare layer. 3. Add additional flare circles based on the input parameters. 4. Apply Gaussian blur to soften the flare. 5. Create and apply a radial gradient mask for natural fading. 6. Simulate chromatic aberration by applying different blurs to color channels. 7. Blend the flare with the original image using screen blending mode. Examples: >>> import numpy as np >>> import albumentations as A >>> image = np.random.randint(0, 256, [1000, 1000, 3], dtype=np.uint8) >>> flare_center = (500, 500) >>> src_radius = 50 >>> src_color = (255, 255, 200) >>> circles = [ ... (0.1, (550, 550), 10, (255, 200, 200)), ... (0.2, (600, 600), 5, (200, 255, 200)) ... ] >>> flared_image = A.functional.add_sun_flare_physics_based( ... image, flare_center, src_radius, src_color, circles ... ) References: - Lens flare: https://en.wikipedia.org/wiki/Lens_flare - 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 Nr$r'rI)r-ZrrHgQ?rrffffff?rr2rd)rgrMr1rrr,r%rLcosradiansrsinlinerogridsqrtr rlistr0r7)r:r4r5r6r7r8rr flare_layerangle end_pointrrrr!r+r*r^channelss rDadd_sun_flare_physics_basedrTs-LXXZFIIbqMMF--2::6KJJ{*D"  Q"&&E):";c%>P"PP Q  Q"&&E):";c%>P"PP Q  I!D "#*4 ;D$JC#*"";r"MK 88GVGVeVO $DAq 77A Q'A-!_1D0JJ KD rwwts51C78!Q? ?D 99dVaZ D4KCIIk*+H""  HQK ""  HQK ))H%K 3#00 1SGSrFcUR[R:XaE[R"SSS5U-S-n[ XR [R5SS9$[R "X5$)aApply gamma transformation to an image. This function applies gamma transformation to an image by raising each pixel value to the power of gamma. The result is a non-linear transformation that can enhance or reduce the contrast of the image. Args: img (np.ndarray): The image to apply gamma transformation to. gamma (float): The gamma value to apply. Returns: np.ndarray: The gamma transformed image. rg?gp?rdFr*)r(r1r6r2rr5r)r:gammatables rDgamma_transformr~sY yyBHH1k95>#Ec<<15AA 88C rFc[R"U[R5n[R"U5upVUR USU-UR SSS9nUR SX-UR SSS9nUS==U- ss'[USXr-SUS- -5US'[R"U[R5n [R"U SSU S 9$) aRApply poisson noise to an image to simulate camera sensor noise. Args: image (np.ndarray): Input image. Currently, only RGB images are supported. color_shift (float): The amount of color shift to apply. intensity (float): Multiplication factor for noise values. Values of ~0.5 produce a noticeable, yet acceptable level of noise. random_generator (np.random.Generator): If specified, this will be random generator used for noise generation. Returns: np.ndarray: The noised image. Image types: uint8, float32 Number of channels: 3 rHNr$rrr.rHrout) r,r-r meanStdDevpoissonrMrr rr1r ) image color_shift intensityrhlsrstddevluminance_noise color_noise noised_hlss rD iso_noisers8 ,,uc// 0Cs#IA&..q I YYr]/O#))  YYr]*K K;K F #sS['89CK c3#4#45J 77:q! 44rFcL[R"U[R5$)aConvert an RGB image to grayscale using the weighted average method. This function uses OpenCV's cvtColor function with COLOR_RGB2GRAY conversion, which applies the following formula: Y = 0.299*R + 0.587*G + 0.114*B Args: img (np.ndarray): Input RGB image as a numpy array. Returns: np.ndarray: Grayscale image as a 2D numpy array. Image types: uint8, float32 Number of channels: 3 )r,r-r9rjs rDto_gray_weighted_averagers( <<S// 00rFcR[R"U[R5S$)aConvert an RGB image to grayscale using the L channel from the LAB color space. This function converts the RGB image to the LAB color space and extracts the L channel. The LAB color space is designed to approximate human vision, where L represents lightness. Key aspects of this method: 1. The L channel represents the lightness of each pixel, ranging from 0 (black) to 100 (white). 2. It's more perceptually uniform than RGB, meaning equal changes in L values correspond to roughly equal changes in perceived lightness. 3. The L channel is independent of the color information (A and B channels), making it suitable for grayscale conversion. This method can be particularly useful when you want a grayscale image that closely matches human perception of lightness, potentially preserving more perceived contrast than simple RGB-based methods. Args: img (np.ndarray): Input RGB image as a numpy array. Returns: np.ndarray: Grayscale image as a 2D numpy array, representing the L (lightness) channel. Values are scaled to match the input image's data type range. Image types: uint8, float32 Number of channels: 3 r)r,r-rrjs rDto_gray_from_labr&s!B <<S.. / 77rFcUR[R5n[R"USS9[R"USS9-S- $)zConvert an image to grayscale using the desaturation method. Args: img (np.ndarray): Input image as a numpy array. Returns: np.ndarray: Grayscale image as a 2D numpy array. Image types: uint8, float32 Number of channels: any rIrr$)r5r1rrr)r: float_images rDto_gray_desaturationrJs<"**RZZ(K FF;R (266+B+G G1 LLrFc^[R"USS9RUR5$)a8Convert an image to grayscale using the average method. This function computes the arithmetic mean across all channels for each pixel, resulting in a grayscale representation of the image. Key aspects of this method: 1. It treats all channels equally, regardless of their perceptual importance. 2. Works with any number of channels, making it versatile for various image types. 3. Simple and fast to compute, but may not accurately represent perceived brightness. 4. For RGB images, the formula is: Gray = (R + G + B) / 3 Note: This method may produce different results compared to weighted methods (like RGB weighted average) which account for human perception of color brightness. It may also produce unexpected results for images with alpha channels or non-color data in additional channels. Args: img (np.ndarray): Input image as a numpy array. Can be any number of channels. Returns: np.ndarray: Grayscale image as a 2D numpy array. The output data type matches the input data type. Image types: uint8, float32 Number of channels: any rIr)r1meanr5r(rjs rDto_gray_averager_s$> 773R ' ' 22rFc,[R"USS9$)aConvert an image to grayscale using the maximum channel value method. This function takes the maximum value across all channels for each pixel, resulting in a grayscale image that preserves the brightest parts of the original image. Key aspects of this method: 1. Works with any number of channels, making it versatile for various image types. 2. For 3-channel (e.g., RGB) images, this method is equivalent to extracting the V (Value) channel from the HSV color space. 3. Preserves the brightest parts of the image but may lose some color contrast information. 4. Simple and fast to compute. Note: - This method tends to produce brighter grayscale images compared to other conversion methods, as it always selects the highest intensity value from the channels. - For RGB images, it may not accurately represent perceived brightness as it doesn't account for human color perception. Args: img (np.ndarray): Input image as a numpy array. Can be any number of channels. Returns: np.ndarray: Grayscale image as a 2D numpy array. The output data type matches the input data type. Image types: uint8, float32 Number of channels: any rIr)r1rrjs rD to_gray_maxrsB 66#B rFcURnURSURS5n[SS9nUR U5nURURSS5n[ US5nU[ R:Xa [XQS9$U$)aQConvert an image to grayscale using Principal Component Analysis (PCA). This function applies PCA to reduce a multi-channel image to a single channel, effectively creating a grayscale representation that captures the maximum variance in the color data. Args: img (np.ndarray): Input image as a numpy array with shape (height, width, channels). Returns: np.ndarray: Grayscale image as a 2D numpy array with shape (height, width). If input is uint8, output is uint8 in range [0, 255]. If input is float32, output is float32 in range [0, 1]. Note: This method can potentially preserve more information from the original image compared to standard weighted average methods, as it accounts for the correlations between color channels. Image types: uint8, float32 Number of channels: any rIr$rH) n_componentsNmin_max) target_dtype) r(reshaperMr fit_transformrr1r6r)r:r(pixelspca pca_result grayscales rD to_gray_pcars8 IIE [[SYYq\ *F 1 C""6*J""399Ra=1I#Iy9I8=8I:i 4XyXrFc US:Xa [U5nOhUS:Xa [U5nOVUS:Xa [U5nODUS:Xa [U5nO2US:Xa [ U5nO US:Xa [ U5nO[ SU35e[X15$)a+Convert an image to grayscale using a specified method. This function converts an image to grayscale using a specified method. The method can be one of the following: - "weighted_average": Use the weighted average method. - "from_lab": Use the L channel from the LAB color space. - "desaturation": Use the desaturation method. - "average": Use the average method. - "max": Use the maximum channel value method. - "pca": Use the Principal Component Analysis method. Args: img (np.ndarray): Input image as a numpy array. num_output_channels (int): The number of channels in the output image. method (Literal["weighted_average", "from_lab", "desaturation", "average", "max", "pca"]): The method to use for grayscale conversion. Returns: np.ndarray: Grayscale image as a 2D numpy array. weighted_averagefrom_lab desaturationaveragerrzUnsupported method: )rrrrrrrzgrayscale_to_multichannel)r:num_output_channelsmethodr)s rDto_grayrsB##)#. : !#& > !%c* 9  % 5S! 5S!/x899 $V AArFcrUS:XaU$[R"U5n[R"U/U-5$)aBConvert a grayscale image to a multi-channel image. This function takes a 2D grayscale image or a 3D image with a single channel and converts it to a multi-channel image by repeating the grayscale data across the specified number of channels. Args: grayscale_image (np.ndarray): Input grayscale image. Can be 2D (height, width) or 3D (height, width, 1). num_output_channels (int, optional): Number of channels in the output image. Defaults to 3. Returns: np.ndarray: Multi-channel image with shape (height, width, num_channels) rH)r1squeezer,r7)grayscale_imagersqueezeds rDrrs9(azz/*H 99hZ"55 66rFcURSSupE[R"USUUUS9n[R"XeU4US9$)aDownscale and upscale an image. This function downscales and upscales an image using the specified interpolation methods. The downscaling and upscaling are performed using the cv2.resize function. Args: img (np.ndarray): Input image as a numpy array. scale (float): The scale factor for the downscaling and upscaling. down_interpolation (int): The interpolation method for the downscaling. up_interpolation (int): The interpolation method for the upscaling. Returns: np.ndarray: The downscaled and upscaled image. Nr$)fxfy interpolationr)rMr,resize)r:rvdown_interpolationup_interpolationrr downscaleds rD downscaler sJ.IIbqMMF   ( J ::j&/AQ RRrFc U$)aCNo-op function. This function is a no-op and returns the input object unchanged. It is used to satisfy the type checker requirements for the `noop` function. Args: input_obj (Any): The input object to return unchanged. **params (Any): Additional keyword arguments. Returns: Any: The input object unchanged. r) input_objparamss rDnooprCs  rFc URn[U5nURSU5n[R"USS9nXE- nUS:Xa"[R "U5nUSU-U-nO[R "USS9n [RRU 5upU SSS2R5n Xn U SS2U 4n [R"[R"U [R"X-55UR5RnXH-n U RU5n [R"U SSU S9$) a5Perform 'Fancy PCA' augmentation on an image with any number of channels. Args: img (np.ndarray): Input image alpha_vector (np.ndarray): Vector of scale factors for each principal component. Should have the same length as the number of channels in the image. Returns: np.ndarray: Augmented image of the same shape, type, and range as the input. Image types: uint8, float32 Number of channels: Any Note: - This function generalizes the Fancy PCA augmentation to work with any number of channels. - It preserves the original range of the image ([0, 255] for uint8, [0, 1] for float32). - For single-channel images, the augmentation is applied as a simple scaling of pixel intensity variation. - For multi-channel images, PCA is performed on the entire image, treating each pixel as a point in N-dimensional space (where N is the number of channels). - The augmentation preserves the correlation between channels while adding controlled noise. - Computation time may increase significantly for images with a large number of channels. References: ImageNet classification with deep convolutional neural networks: Krizhevsky, A., Sutskever, I., & Hinton, G. E. (2012): In Advances in neural information processing systems (pp. 1097-1105). rIrrrHF)rowvarNr)rMrrr1rstdcovlinalgeighargsortdotdiagrr )r: alpha_vector orig_shaper img_reshapedimg_mean img_centeredstd_devnoiseimg_coveig_valseig_vecs sort_permimg_pcas rD fancy_pcarTs0DJ#C(L;;r<0Lww|!,H*Lq&&&Q')L8&&e4 YY^^G4TrTN**, &AyL) FF8RWW\%<= > NN  !  "Gooj)G 777Aqg ..rFc^US:Xa[R"U5$US:XaU$[XSS9$)apAdjust the brightness of an image. This function adjusts the brightness of an image by multiplying each pixel value by a factor. The brightness is adjusted by multiplying the image by the factor. Args: img (np.ndarray): Input image as a numpy array. factor (np.ndarray): The factor to adjust the brightness by. Returns: np.ndarray: The adjusted image. rrHFr*)r1rrr:factors rDadjust_brightness_torchvisionrs3{}}S!! { C //rFc|US:XaU$[U5(aUR5O2[R"U[R5R5nUS:XaKUR [ R:wa[US-5n[ R"XUR S9$[XUSU- -SS9$)acAdjust the contrast of an image. This function adjusts the contrast of an image by multiplying each pixel value by a factor. The contrast is adjusted by multiplying the image by the factor. Args: img (np.ndarray): Input image as a numpy array. factor (float): The factor to adjust the contrast by. Returns: np.ndarray: The adjusted image. rHrrr'Fr*) rrr,r-r9r(r1rrLrr)r:rrs rDadjust_contrast_torchvisionrs{ +C00388:cll3HZHZ6[6`6`6bD { 99 "tcz?D||CSYY77 TQZ%8% HHrFc US:Xd[U5(aU$[R"U[R5n[R"U[R5nUS:XaU$[R "XUSU- US9$)aAdjust the saturation of an image. This function adjusts the saturation of an image by multiplying each pixel value by a factor. The saturation is adjusted by multiplying the image by the factor. Args: img (np.ndarray): Input image as a numpy array. factor (float): The factor to adjust the saturation by. gamma (float): The gamma value to use for the adjustment. Returns: np.ndarray: The adjusted image. rHr)r|)rr,r-r9r.r)r:rr|grays rDadjust_saturation_torchvisionrsl*{(-- <<S// 0D <<c00 1DQ;4_COOCq6zY^$__rFct[R"U[R5n[R"SS[R S9n[R "USU--S5R[R5n[USUSS9US'[R"U[R5$)Nrr&r'r)rFr*) r,r-r/r1r2r3r4r5r6rr8)r:rrUs rD_adjust_hue_torchvision_uint8rs ,,sC-- .C ))As"(( +C &&sV|#S ) 0 0 :CVc59CK <<S.. //rFc^[U5(dUS:XaU$UR[R:Xa [ X5$[ R "U[ R5n[R"USUS--S5US'[ R "U[ R5$)zAdjust the hue of an image. This function adjusts the hue of an image by adding a factor to the hue value. Args: img (np.ndarray): Input image. factor (float): The factor to adjust the hue by. Returns: np.ndarray: The adjusted image. rrih) rr(r1r6rr,r-r/r4r8rs rDadjust_hue_torchvisionrs#&A+  yyBHH,S99 ,,sC-- .C&&Vv|3S9CK <<S.. //rFc [R"U5(dU$URnUbd[URSS5nXc:aGX6- nURSSup[ X-5[ X-5p[ R "X U 4U5n[UUSS9n Sn [URn[R"U5nUR[:Xa[R"USS9n[U5n[U5HnUSU4n[R "U 5nUSS:XaUS Sn[#U5HunnUU[%U5-(dMU U:Hn[R&"UU5nURR(S ;a6[ [R*"U55n[-[UU 5U5nOUnUUU'M M XPR:wa[ R "XSSU5$U$) aSApply superpixels to an image. This function applies superpixels to an image using the SLIC algorithm. The superpixels are applied by replacing the pixels in the image with the mean intensity of the superpixel. Args: image (np.ndarray): Input image as a numpy array. n_segments (int): The number of segments to use for the superpixels. replace_samples (Sequence[bool]): The samples to replace. max_size (int | None): The maximum size of the superpixels. interpolation (int): The interpolation method to use. Returns: np.ndarray: The superpixels applied to the image. Nr$r1) n_segments compactnessrrIr.rH)rTub)r1rrrMrrL fgeometricrslicrr(rgrOr rPrrKuniquer[rNrkindrtr)rrreplace_samplesmax_sizerrrrvrr new_height new_widthsegments min_valuerrc image_sp_c unique_labelsidxlabelr^mean_intensityvalues rD superpixelsrs2 66/ " " J5;;r?# ?OE!KKOMF$'$7U]9K %%e)-DmTE H I#EKK0I GGENE zz,,u2.#E*L < 36]  (+  q )!"-M$M2JCsS%99::5(!#D)9!:##((O;   89EE9 5yAE*E#( 4 #3!6GQT_T_F_:  UrNM BjejjrFc[[RX4US9nUR[:Xa$[ U5S:Xa[ R"USS9nU"U5nX- n[ R"U5S-U:nUR[ R5nXU--n [ R"U SSU S9n U"U5n [[X5[USU - 5SS 9$) aApply an unsharp mask to an image. This function applies an unsharp mask to an image using the Gaussian blur function. The unsharp mask is applied by subtracting the blurred image from the original image and then adding the result to the original image. Args: image (np.ndarray): Input image as a numpy array. ksize (int): The kernel size to use for the Gaussian blur. sigma (float): The sigma value to use for the Gaussian blur. alpha (float): The alpha value to use for the unsharp mask. threshold (int): The threshold value to use for the unsharp mask. Returns: np.ndarray: The unsharp mask applied to the image. )ksizerrHrIrrdrrTr*)rr,rrOr!rr1rabsr5rr r r) rrsigmar-rRblur_fnrresidualr^sharp soft_masks rD unsharp_maskres4& nG  zz116Fu6MQR6R 5r* 5>D|H 66( c !I -D ;;rzz "D H$ $E GGE1aU +E I "I & rFc0[R"XU5$)aApply pixel dropout to the image. Args: image (np.ndarray): Input image drop_mask (np.ndarray): Boolean mask indicating which pixels to drop drop_values (np.ndarray): Values to replace dropped pixels with Returns: np.ndarray: Image with dropped pixels )r1rQ)r drop_mask drop_valuess rD pixel_dropoutrs" 88IE 22rFc[XSS9$)a"Apply spatter rain to an image. This function applies spatter rain to an image by adding the rain to the image. Args: img (np.ndarray): Input image as a numpy array. rain (np.ndarray): Rain image as a numpy array. Returns: np.ndarray: The spatter rain applied to the image. Fr*r )r:rains rD spatter_rainr s s% ((rFc[X-USS9$)aVApply spatter mud to an image. This function applies spatter mud to an image by adding the mud to the image. Args: img (np.ndarray): Input image as a numpy array. non_mud (np.ndarray): Non-mud image as a numpy array. mud (np.ndarray): Mud image as a numpy array. Returns: np.ndarray: The spatter mud applied to the image. Fr*r )r:non_mudmuds rD spatter_mudrs" s}c5 11rFcURSSupg[R"S[RS9nXxS'XhS'US- US'US- US '[R"XS S /[RS9n [R"X4S S /[RS9n [ US UU UUU5n [ US UU UUU5n [R "XS U /5$)aApply chromatic aberration to an image. This function applies chromatic aberration to an image by distorting the red and blue channels. Args: img (np.ndarray): Input image as a numpy array. primary_distortion_red (float): The primary distortion of the red channel. secondary_distortion_red (float): The secondary distortion of the red channel. primary_distortion_blue (float): The primary distortion of the blue channel. secondary_distortion_blue (float): The secondary distortion of the blue channel. interpolation (int): The interpolation method to use. Returns: np.ndarray: The chromatic aberration applied to the image. Nr$rr'r)rHrHg@)rr$)rHr$rr.r$r)rMr1eyerrJ_distort_channelr) r:primary_distortion_redsecondary_distortion_redprimary_distortion_bluesecondary_distortion_bluerrr camera_matdistortion_coeffs_reddistortion_coeffs_blue red_distortedblue_distorteds rDchromatic_aberrationrs4IIbqMMF,Jtts{Jt|JtHH 1a@jj XX QBjj % F   M& F   N 99m[.A BBrFc [R"UUSUXC4[RS9upg[R"UUUU[RS9$)N) cameraMatrix distCoeffsRnewCameraMatrixrm1type)r borderMode)r,initUndistortRectifyMapCV_32FC1remapBORDER_REPLICATE)channelrdistortion_coeffsrrrmap_xmap_ys rDrrsV..$ "_|| LE 99  #''  rFi )gk+ݓ?gӼ?g_LU?i )a+e?gMSt$?gZd;O?i)gD?gs?g_L?i)g?r0g%䃞?)gOjM?r0gm?)glV}?r/g F%u?)g{Pk?r.g:#J{/?),.02468:)g,Ԛ?gAc]K?g QI?)goʡ?gZӼ?gY?)gDio?g QI?g46W[?)g]Fx ?gX2ı.?g:H?)gjM?g|a2U0?r-r2)gHP?g-1?g"~j?r3)g[B>٬?߾3?g?ܵ?)gʡE?r:g`"?)gۊe?r:gH}8?)gK7?r:g58EGr?)gJ4?r:g' ?)g+e?r:g?)gǘ?r:g/n?)r4r5r6r7r8r9) blackbodyciedz!dict[str, dict[int, list[float]]]PLANCKIAN_COEFFScUR5n[[UR55n[ [UR55n[ R "XU5nSn[ X-U-U5n[X-S-U-U5nXg:Xa![ R"[UU5nOUX- Xv- - n SU - n U [ R"[UU5-U [ R"[UU5--n[USS2SS2S4USUS- SS9USS2SS2S4'[USS2SS2S4USUS- SS9USS2SS2S4'U$)aApply Planckian jitter to an image. This function applies Planckian jitter to an image by linearly interpolating between the two closest temperatures in the PLANCKIAN_COEFFS dictionary. Args: img (np.ndarray): Input image as a numpy array. temperature (int): The temperature to apply. mode (Literal["blackbody", "cied"]): The mode to use. Returns: np.ndarray: The Planckian jitter applied to the image. irHNrTr*r$) rgrr=keysrr1r rJr) r: temperaturermin_tempmax_temprnt_leftt_rightcoeffsw_rightw_lefts rDplanckian_jitterrHjs( ((*C#D)..01H#D)..01H''+:K D   $F  q D(G *4089'G,<=W"((#3D#9&#ABBWrxx T "7 +P F  ( Aq!G q F1IC1aL ( Aq!G q F1IC1aL JrFc[XSS9$)aAdd noise to an image. This function adds noise to an image by adding the noise to the image. Args: img (np.ndarray): Input image as a numpy array. noise (np.ndarray): Noise as a numpy array. Returns: np.ndarray: The noise added to the image. Fr*r )r:rs rD add_noiserJs s5 ))rFc UR[:XaUS[R4nURSSupEXE-nUR [R 5[R"US-5- n[Xa- S-5n[R"US-XX5n [R"US-XH5n [R"U V V s/sHoHoU:dM X:dMX4PM M sn n 5n S[R"XE4[RS9-n[R"XE4[R5n[U5GHun[!U 5Hunn[US5[US 5p[S X- 5[#XKU-S-5nn[S X- 5[#X\U-S-5nnUUU2UU24nUX{U 4- n[R$"US-SS 9n[R&UU2UU24unnUU - S-UU - S--US-- nUUU--nUUUU2UU24:nUUUUU2UU24U'UUUU2UU24U'M [[)U 55HWnUU:Hn[R*"U5(dM%[R,"[R."U5S S 9SSS2U U'MY GMx U$s sn n f) aSimple Linear Iterative Clustering (SLIC) superpixel segmentation using OpenCV and NumPy. Args: image (np.ndarray): Input image (2D or 3D numpy array). n_segments (int): Approximate number of superpixels to generate. compactness (float): Balance between color proximity and space proximity. max_iterations (int): Maximum number of iterations for k-means. Returns: np.ndarray: Segmentation mask where each superpixel has a unique label. .Nr$ư>rrIr'rHrr)rOr r1rrMr5rrrLr2rJonesrfullinfrKr[rrhrMrNrrrargwhere)rrrmax_iterationsrr num_pixelsimage_normalized grid_stepx_rangey_ranger+r*centerslabels distancesrrTry_lowy_highx_lowx_highcrop color_diffcolor_distanceyyxxspatial_distancedistancer^s rDrrs$ zz,,c2::o&KKOMFJ||BJJ/"&&2FFZ,45Iii Q9Gii Q:Ghh NA'QY1:!'NG "''6/: :F0I > ""7+IAvvay>3vay>q 1=13v9}q?P3Q6E1=13u)ma>O3P6E$E&L%,$>?D 0A 66JVVJM;NXXeFlE&L89FB!#aA aA =)Q,O % 6F(FFHif eFl(BCCD:B4.IeFlE&L0 1$ 778F5<v- .t 4',,s7|$AQ;Dvvd||WWR[[%6Q?"E %/#8 MG OsK #K * K c [R"US5nX1S--U- n[URU5R [ R 5USS9n[[ R"USSUS9S5$) zApply shot noise to the image. Args: img (np.ndarray): Input image scale (float): Scale factor for the noise random_generator (np.random.Generator): Random number generator Returns: np.ndarray: Image with shot noise g@rLTr*rrHrg]tE?) r,powrrr5r1rrr )r:rvr img_linear scaled_img noisy_imgs rD shot_noiserj st&c"Jt|+u4J%  ,33BJJ? I Aqi8' BBrFcUS:a,[R"USU5n[XU- U- 5nXC4$[X5n[X*U- 5nXC4$)zGet safe brightness and contrast parameters. Args: alpha (float): Contrast factor beta (float): Brightness factor max_value (float): Maximum pixel value Returns: tuple[float, float]: Safe alpha and beta values r)r1r rr)r-betar safe_beta safe_alphas rD#get_safe_brightness_contrast_paramsro# sd  qyGGD!Y/ Y!6) CD    (  Y 67   rFc,Uc#[R"U[RS9$URSS5n[R "U5 US:Xa[ UUUUU5$US:Xa$US:Xa[UUUUU5$[UUUUU5$USSup[S [X-55n [S [X-55n X4USS-n US:Xa[UU UUU5n O[UU UUU5n [R"XU 4[RS 9$) aGenerate noise with optional approximation for speed. This function generates noise with optional approximation for speed. Args: noise_type (Literal["uniform", "gaussian", "laplace", "beta"]): The type of noise to generate. spatial_mode (Literal["constant", "per_pixel", "shared"]): The spatial mode to use. shape (tuple[int, ...]): The shape of the noise to generate. params (dict[str, Any] | None): The parameters of the noise to generate. max_value (float): The maximum value of the noise to generate. approximation (float): The approximation to use for the noise to generate. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The noise generated. Nr'rirrsharedr$rHr)r1rVrrr, setRNGSeedgenerate_constant_noisegenerate_shared_noisegenerate_per_pixel_noiserrLrr INTER_LINEAR) noise_type spatial_moderMrr approximationrcv2_seedrrreduced_height reduced_width reduced_shapers rDgenerate_noiser~C sS4~xxRZZ00((E2HNN8z!&         8 #(  (        "1IMFC 678N3u456M#3eABi?Mx%       )          UUO3CSCS TTrFcV[U5[:aUSOSn[UU4UUU5$)a'Generate constant noise. This function generates constant noise by sampling from the noise distribution. Args: noise_type (Literal["uniform", "gaussian", "laplace", "beta"]): The type of noise to generate. shape (tuple[int, ...]): The shape of the noise to generate. params (dict[str, Any]): The parameters of the noise to generate. max_value (float): The maximum value of the noise to generate. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The constant noise generated. rIrH)rNr sample_noise)rwrMrrrrs rDrsrs s9,!$E -D D59!L    rFc[XX#U5$)a*Generate per-pixel noise. This function generates per-pixel noise by sampling from the noise distribution. Args: noise_type (Literal["uniform", "gaussian", "laplace", "beta"]): The type of noise to generate. shape (tuple[int, ...]): The shape of the noise to generate. params (dict[str, Any]): The parameters of the noise to generate. max_value (float): The maximum value of the noise to generate. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The per-pixel noise generated. )r)rwrMrrrs rDruru s,  6>N OOrFcUS:Xa[XU5U-$US:Xa[XU5U-$US:Xa[XU5U-$US:Xa[XU5U-$[ SU35e)aSample from specific noise distribution. This function samples from a specific noise distribution. Args: noise_type (Literal["uniform", "gaussian", "laplace", "beta"]): The type of noise to generate. size (tuple[int, ...]): The size of the noise to generate. params (dict[str, Any]): The parameters of the noise to generate. max_value (float): The maximum value of the noise to generate. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The noise sampled. uniformgaussianlaplacerlzUnknown noise type: )sample_uniformsample_gaussiansample_laplace sample_betarz)rwrrrrs rDrr s,Yd,<= IIZt-=>JJYd,<= IIV4)9:YFF +J<8 99rFc h[U5S:XaUSnUSn[U5S:XaX4-nO)[U5U:a[SUS[U535e[R"USUVVs/sHupVUR XV5PM snn5$USSupVUR XVUS9$s snnf)a Sample from uniform distribution. Args: size (tuple[int, ...]): Size of the output array params (dict[str, Any]): Distribution parameters random_generator (np.random.Generator): Random number generator Returns: np.ndarray | float: Sampled values rHrangesrz%Not enough ranges provided. Expected z, got Nr)rNrzr1rJr)rrrrrlowhighs rDrr s  4yA~!Aw v;! *F [< '7 ~VCPVK=Y xxBH,BW XBWYS  % %c 0BW X  x #IC  # #CD # 99 Ys/B. cUSSUSS:XaUSSOUR"US6nUSSUSS:XaUSSOUR"US6n[U5[:aUSOSnU[R"U4[R S9-nU[R"U4[R S9-n[R "US9n[R"XUS9 UR[R 5$) akSample from Gaussian distribution. This function samples from a Gaussian distribution. Args: size (tuple[int, ...]): The size of the noise to generate. params (dict[str, Any]): The parameters of the noise to generate. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The Gaussian noise sampled. mean_rangerrH std_ranger$)rMr()rM)rrr) rrNr r1rMrrVr,randnr5) rrrrrr mean_vectorstd_dev_vectorgaussian_sampled_arrs rDrr s( ,  "f\&:1&= = |Q  % %vl'; <  + q !VK%8%; ; {A  % %vk': ; "$i*AA47qL bjjIIK277, KKN88$/II&P  & &rzz 22rFcjUR"US6nUR"US6nURX4US9$)ahSample from Laplace distribution. This function samples from a Laplace distribution. Args: size (tuple[int, ...]): The size of the noise to generate. params (dict[str, Any]): The parameters of the noise to generate. random_generator (np.random.Generator): The random number generator to use. Returns: np.ndarray: The Laplace noise sampled. r scale_range)rrvr)rr)rrrrrvs rDrr= sD$  " "F<$8 9C  $ $f]&; URSS- S-S-nURSS- S-S-n[R"X#4[RS9nT R U*XU45R [R5nXSSS2SSS24-USSS2SSS24'[ R"US[[ RS9nUS:nXFU-U-- n[ R"US[[ RS9nUS:n XHU-U -- n[ R"USSS[ R[ RS9$)NrrHr$r'rI) borderType)rMr1rVrrr5r,filter2DDIAMOND_KERNELBORDER_CONSTANT SQUARE_KERNEL normalize NORM_MINMAXCV_32F) current_grid noise_scale next_height next_width expanded_grid all_noisediamond_interpolation diamond_masksquare_interpolation square_maskrs rDone_diamond_square_step8generate_plasma_pattern..one_diamond_square_step sK#))!,q0A59 "((+a/14q8 +!:"**M %,,k\;V`Habiijljtjtu #/3Q3!81D"D cc3Q3h!$ ]B[^[n[n o,q0 );|KK  #||M2}Y\YlYlm*Q. :kII }}]D!QszzZZrFr$rHrIrNrr')rrrfloatrr)rr1ceillog2rLrrKrr5r r,rrr) target_shape roughnessrr max_dimensionpower_of_two_size total_stepsrT noise_scales plasma_gridrs ` rDgenerate_plasma_patternr s&[6 %MRWWRWW]Q->%?@@1Dbgg/!34q89K::U;5GH5G!|5GHIL#**2q&9@@LK$ -kG $ 77 k"3LO"35F|A5F"FGqRSUXUdUdlolvlvw   Is D:cUS:XaUS:XaU$UR5nUR[:a:[R"US[R 4SSUR S45nUS:wa[X1SS9n[XSS9nUS:wa9UR5n[X2SS9S-n[XSS9nUSU- -n[XSS9$U$) a&Apply plasma-based brightness and contrast adjustments. This function applies plasma-based brightness and contrast adjustments to an image. Args: img (np.ndarray): The image to apply the brightness and contrast adjustments to. brightness_factor (float): The brightness factor to apply. contrast_factor (float): The contrast factor to apply. plasma_pattern (np.ndarray): The plasma pattern to use for the brightness and contrast adjustments. Returns: np.ndarray: The image with the brightness and contrast adjustments applied. r.rHrIFr*Tr) rgrOr r1tilerrMrr r)r:brightness_factorcontrast_factorplasma_patternbrightness_adjustmentrcontrast_weights mean_factors rD apply_plasma_brightness_contrastr' s.A/Q"6 ((*C xx))RZZ!@1aSUBWXA (TY Z#d;!xxz#NUSVWWsd;c$445 3T22 JrFclX!-nUR[:aUS[R4nUSU- -$)zApply plasma shadow to the image. Args: img (np.ndarray): Input image intensity (float): Shadow intensity plasma_pattern (np.ndarray): Plasma pattern to use Returns: np.ndarray: Image with plasma shadow .rH)rOr r1r)r:rrscaled_patterns rDapply_plasma_shadowrY s?$$/N xx))'RZZ8 !n$ %%rFc  US:XaR[R"SSU[RS9SSS24[R"US4[RS9-$US:XaR[R"SSU[RS9SSS24[R"US4[RS9-$US:XaR[R"SSU[RS9SS2S4[R"SU4[RS9-$US:XaR[R"SSU[RS9SS2S4[R"SU4[RS9-$US;GaU[R"SSU[RS9SSS24n[R"SSU[RS9SS2S4nUS :Xa7[R "X4-SSS[R [RS9$US :Xa;[R "SU- U-SSS[R [RS9$US :Xa>[R "SU- SU- -SSS[R [RS9$[R "USU- -SSS[R [RS9$[R"SSU[RS9SS2S4n[R"SSU[RS9SSS24n[R"U5n[R"U5n[R"U5n[R"X6US 9 [R"XGUS 9 X4-$) a0Create a directional gradient in [0, 1] range. This function creates a directional gradient in the [0, 1] range. Args: height (int): The height of the image. width (int): The width of the image. angle (float): The angle of the gradient. Returns: np.ndarray: The directional gradient. rrHr'Nr)rEi)rDrFi;rDrFrr) r1rrrMr,rrrdeg2radmathrIrKr)rrrQr*r+ angle_radcos_asin_as rDcreate_directional_gradientru s z{{1abjj9$'BRWWfVW[`b`j`jEkkk |{{1abjj9$'BRWWfVW[`b`j`jEkkk {{{1arzz:1d7CbggqRWj`b`j`jFkkk |{{1arzz:1d7CbggqRWj`b`j`jFkkk ## KK1e2:: 6tQw ? KK1fBJJ 74 @ B;==aCOO3::V V C<==!a%1dAq#//QTQ[Q[\ \ C<==!a%AE!2D!QWZWaWab b}}Q!a%[$1cooSZZXX Aq& 3AtG!QPGD## [[&& GLL*6GDGGGQG$ xx//))WI ! 45 S **rFcUS:XaUR5$URSSupEXRS-nXBS-nS[XE5U-S--n[RSU2SU24upU R [R 5n U R [R 5n X-n X-n [R"XU S9 [R"XU S9 X-n [R"U SU- U S9 [R"XS9 [R"XU S9 [R"U SU S9 UR[:Xa'[R"U /URS-5n [X 5$)zApply gaussian illumination to the image. Args: img (np.ndarray): Input image intensity (float): Illumination intensity center (tuple[float, float]): The center of the illumination. sigma (float): The sigma of the illumination. rNr$rHrrI)rgrMrr1rMr5rr,rexpr rOr!r7r) r:rrrrrcenter_xcenter_ysigma2r+r*s rDapply_gaussian_illuminationr sG A~xxzIIbqMMFay Hq !H #f$u,2 2F 88GVGVeVO $DA A AMAMALL1LL1 ALLBKQ'GGALL1%GGAqa xx// IIqcCIIaL( ) S $$rFc >UR5n[U5n[URnUR[ :a[ R"U5n/n[U5HgupUbX:XaURS5 M UcSOX:gn [ R"U /S/U S/SU/5n URU R55 Mi [U5Hn UbX:XaM UR[ :a WU n WU n O8UcSOX:gn [ R"U/S/U S/SU/5R5n Un [X5upX::aMx[XXU5nUbX/U'UR[ :a[X5USU 4'M[X5nM U$)a<Apply automatic contrast enhancement. Args: img (np.ndarray): Input image cutoff (float): Cutoff percentage for histogram ignore (int | None): Value to ignore in histogram method (Literal["cdf", "pil"]): Method to use for contrast enhancement Returns: np.ndarray: Image with enhanced contrast Nrr&.)rgrrr(rOr r,r0r[appendrerfrKget_histogram_boundscreate_contrast_lutr)r:cutoffignorerr)rrrShistsrTr)r^histlohirUs rD auto_contrastr3 s&XXZF#C(L#CII.I xx))99S>"$#H-JA!ak T"!>40AD<< A3sea^LD LL & .<   !+  88- -8DqkG!>4 D<<sD3%!YHNNPDG%d3 8 !$B6B   K 88- -#G1F36NG)F/!2 MrFcX:a#[R"S[RS9$US:XaXUS-nUR5nUSS:Xa#[R"S[RS9$XfS- U-USUS- - n[R"S[RS9n[R "[R "U5SU5R[R5XqUS-&X7US-S&U$X2U- - n[R"S[S9n [R "[R "X- U-5SU5R[R5nSUSU&X7US-S&U$)aCreate lookup table for contrast adjustment. This function creates a lookup table for contrast adjustment. Args: hist (np.ndarray): Histogram of the image. min_intensity (int): Minimum intensity of the histogram. max_intensity (int): Maximum intensity of the histogram. max_value (int): Maximum value of the lookup table. method (Literal["cdf", "pil"]): Method to use for contrast enhancement. Returns: np.ndarray: Lookup table for contrast adjustment. r&r'cdfrHrIrN) r1rVr6rjr2r rtr5r) r min_intensity max_intensityrr hist_rangerrUrvindicess rDrrr s_,%xx288,, -!*;< ! r7a<99S1 1V|y(CGc!f,<=hhs"((+13#91U1\1\]_]e]e1fMA-.#,MA     6 7Eii5)G ''"((G3u<=q) L S STVT\T\ ]CC(  JrFcU(dE[R"U5Sn[U5S:Xag[US5[US54$[ UR 55nUS:XagX1-S- n[U5S:XaN[R "XS:H5(a.[[U5U-S- 5n[U5U- S- nXV4$SnSn[[U55HnXpU- nXt:dMUS-n O [U[U5S- 5nSn[U5S- n[[U5S- SS5HnXpU- nXt:dMUn O XV:a[U5S- S -n X4$XV4$) aGet the low and high bounds of the histogram. This function gets the low and high bounds of the histogram. Args: hist (np.ndarray): Histogram of the image. cutoff (float): Cutoff percentage for histogram. Returns: tuple[int, int]: Low and high bounds of the histogram. rrrIgY@r&drHrr$) r1nonzerorNrLrrhallrKr) rrnon_zero_intensities total_pixels pixels_to_cutrrrjrT mid_points rDrr s !zz$/2 # $ )'*+S1Eb1I-JJJ$Lq )E1M 4yCBFF47?33CI.45 D M1A5 ++FM 3t9 q'  "EM    s4y1}5MFIMM 3t9q="b )q'  "M  *$Y]q( ##  ''rFcU(d[U5S:XaURSS/UUSU- /S9$URSS/USSUSU- /S9n[U5S:XaU$[R"USUSSS9$) aTGenerate dropout mask. This function generates a dropout mask. Args: shape (tuple[int, ...]): Shape of the output mask per_channel (bool): Whether to apply dropout per channel dropout_prob (float): Dropout probability random_generator (np.random.Generator): Random number generator Returns: np.ndarray: Dropout mask r$TFrH)pNrr)rNchoicer1rX)rM per_channel dropout_probrmask_2ds rD get_drop_maskr s(c%jAo&& 5M Q-.'  %% u  bq \) *&G 5zQ 99WY'q ::rFcU[R:Xa"URS[[U5UUS9$U[R :Xa UR SSUS9RU5$[SU35e)zGenerate random values. Args: channels (int): Number of channels dtype (np.dtype): Data type of the output array random_generator (np.random.Generator): Random number generator Returns: np.ndarray: Random values r)rr(rHrzUnsupported dtype: ) r1r6rrLrrrr5rz)rSr(rs rDgenerate_random_valuesr s  (( #E* + )    ''18'<CCEJJ *5'2 33rFcUc"[U5n[X0RU5nOq[U[[ 45(a)[ R"URXRS9$[ R"XRS9RS5nURS:Xa-[ R"URUSURS9$[ R"URSS[U54-X@RS9$)aZPrepare values to fill dropped pixels. Args: array (np.ndarray): Input array to determine shape and dtype value (float | Sequence[float] | np.ndarray | None): User-specified drop values or None for random random_generator (np.random.Generator): Random number generator Returns: np.ndarray: Array of values matching input shape Nr'rIr$r) rrr(rrLrr1rNrMrJrrOrN)rJrrrSvaluess rDprepare_drop_valuesr' s  }#E*'++?OP EC< ( (wwu{{E==%{{3;;B? zzQwwu{{F1IU[[AA 775;;r?c&k^3V;; OOrFc8SU;aUS$SU;aUSS$S$)z,Get mask array from input data if it exists.r^masksrNr)datas rDget_mask_arrayrG s- ~F|&$4= 8D8rFc[US-[RSS9nS[R"USS5- n[R "U[R S5n[R"USS[R5upC[R"USS S [RS 9n[U[RS S9n[U5n[R"/S Q/S Q/SQ/[RS9n[X55n[R"USSS[RS 9R[R5nUR[R5U-n[R "USS9nUS:a US U- -nO[R""U5nUSS2SS2S4U-US--nSU0$)a5Generate parameters for rain effect. This function generates parameters for a rain effect. Args: liquid_layer (np.ndarray): Liquid layer of the image. color (np.ndarray): Color of the rain. intensity (float): Intensity of the rain. Returns: dict[str, Any]: Parameters for the rain effect. rdFr*2r2rrHrrrrT)rIr)rIrHrH)rrHr$r')r2r2g?rrrNg?drops)r r1r6r,CannyrrrR THRESH_TRUNCrr(rrJrconvolver5rr) liquid_layerr!rdistrkermm_maxr$s rDget_rain_paramsr-N s$ s*BHHeDL <S1 1D  s{{A 6DmmD"b#*:*:;GA    ''  D bhh -D D>D ((    jj  C D D    ''    fRZZ   BJJ'$.A FF16 "E qy QY MM!  aDjME !Y_ 5E  rFcURupgX:R[R5n[R"U5S:Xa^Xg-n [ S[ SU -55n URXSS9n [R"U[RS9nSURU 'US:a&[R"USUU[RS 9n[R "U5n U S:aX- nOSUS'X-n[R"XgS 4[RS9n [S 5HnXU-U S U4'M [R"U 5n[S 5HCnXS:a.[R "XU S U4- X- SS5US U4'M9SU- US U4'ME U R[R5UR[R5S .$) aGenerate parameters for mud effect. This function generates parameters for a mud effect. Args: liquid_layer (np.ndarray): Liquid layer of the image. color (np.ndarray): Color of the mud. cutout_threshold (float): Cutout threshold for the mud. sigma (float): Sigma for the Gaussian blur. intensity (float): Intensity of the mud. random_generator (np.random.Generator): Random number generator. Returns: dict[str, Any]: Parameters for the mud effect. rrHrF)replacer'rrr"r.)rr )rMr5r1rrhrrLrrflatr,rr(rVrK ones_liker )r(r!cutout_thresholdrrrrrr^rR num_needed flat_indicesmask_maxrrTr s rDget_mud_paramsr6 s0!&&MF  + 3 3BJJ ?D vvd|q^ Cj 012 '..zu.U }}\<"% , qy ++  vvd|H!|T   D ((F1%RZZ 8C1X1XoCF ll3G 1X 8a< ggux#c1f+'=&I1aPGCFO!DjGCFO zz"**%>>"**- rFg&c`?g8?gH?gm?g?g҈}?)gX?g/' ?gH.?)gQkw?g3ı.n?g$?)g?rHg(\?)gQ?r)\(?)皙?g)\(?r9)gQ?gQ?g\(\?)rgQ?g{Gz?)g{Gz?g(\?g ףp= ?)rrQ?)g(\?gffffff?r)g(\?r:r;)g ףp= ?g ףp= ?gzG?)g= ףp=?gQ?gRQ?)rg{Gz?gzG?)ruifrokmacenkostandard high_contrasth_heavye_heavydarklightc[URnURSS5R[R 5n[R "X2- U5n[R"U5*$)zConvert RGB image to optical density. This function converts an RGB image to optical density. Args: img (np.ndarray): Input image. eps (float): Epsilon value. Returns: np.ndarray: Optical density image. rIr)rr(rr5r1rmaximumlog)r:epsr pixel_matrixs rDrgb_to_optical_densityrIsV$CII.I;;r1%,,RZZ8L::l6E ?rFStainNormalizerc6US:Xa [5$[5$)zGet stain normalizer based on method. This function gets a stain normalizer based on a method. Args: method (Literal["vahadane", "macenko"]): Method to use for stain normalization. Returns: StainNormalizer: Stain normalizer. vahadane)VahadaneNormalizerMacenkoNormalizer)rs rDget_normalizerrUBs$*Z#7  P=N=PPrFc,\rSrSrSrSSjrSSjrSrg) rPiQz!Base class for stain normalizers.cSUlgrstain_matrix_target)selfs rD__init__StainNormalizer.__init__Ts #' rFc[e)zFit the stain normalizer to an image. This function fits the stain normalizer to an image. Args: img (np.ndarray): Input image. )NotImplementedError)rZr:s rDfitStainNormalizer.fitWs "!rFrXN)rNoner:rrra)__name__ __module__ __qualname____firstlineno____doc__r[r___static_attributes__rrFrDrPrPQs+( "rFc0\rSrSrSrSSSjjrS SjrSrg) SimpleNMFicaSimple Non-negative Matrix Factorization (NMF) for histology stain separation. This class implements a simplified version of the Non-negative Matrix Factorization algorithm specifically designed for separating Hematoxylin and Eosin (H&E) stains in histopathology images. It is used as part of the Vahadane stain normalization method. The algorithm decomposes optical density values of H&E stained images into stain color appearances (the stain color vectors) and stain concentrations (the density of each stain at each pixel). The implementation uses an iterative multiplicative update approach that preserves non-negativity constraints, which are physically meaningful for stain separation as concentrations and absorption coefficients cannot be negative. This implementation is optimized for stability by: 1. Initializing with standard H&E reference colors from Ruifrok 2. Using normalized projection for initial concentrations 3. Applying careful normalization to avoid numerical issues Args: n_iter (int): Number of iterations for the NMF algorithm. Default: 100 References: - Vahadane, A., et al. (2016): Structure-preserving color normalization and sparse stain separation for histological images. IEEE Transactions on Medical Imaging, 35(8), 1962-1971. - Ruifrok, A. C., & Johnston, D. A. (2001): Quantification of histochemical staining by color deconvolution. Analytical and Quantitative Cytology and Histology, 23(4), 291-299. clXl[R"/SQ/SQ/[RS9Ulg)Nr7r8r')n_iterr1rJrinitial_colors)rZrls rDr[SimpleNMF.__init__s,  hh.. **  rFcURR5n[U5n[R"XR -S5nSn[ UR5HnXR -nXBUR --nXGX-- -n[R"US5nUR U-nUR U-U-nX'X-- -n[R"US5n[U5nM XB4$)zFit the NMF model to optical density. This function fits the NMF model to optical density. Args: optical_density (np.ndarray): Optical density image. Returns: tuple[np.ndarray, np.ndarray]: Stain concentrations and stain colors. rrL)rmrgrOr1rErrKrl) rZoptical_density stain_colorsstain_colors_normalizedstain_concentrationsrGr numerator denominators rDrSimpleNMF.fit_transforms**//1 #4L"A!zz/  (2rFrjcz[U5n[R"[R"USS2S4USS2S45[R5nUSS2S4[R "USS9S-- nUSS2S4[R "USS9S-- nX-U- n[R "U5nSU- nXV4$)aOrder stains using a combination of methods. This combines both angular information and spectral characteristics for more robust identification. Args: stain_colors (np.ndarray): Stain colors. Returns: tuple[int, int]: Hematoxylin and eosin indices. NrHrr$rrL)rOr1r4arctan2pirhargmax)rqangles blue_ratio red_ratioscoreshematoxylin_idx eosin_idxs rDorder_stains_combinedrs%\2LVVBJJ|AqD1<13EF NFad#rvvl'Cd'JKJQT"bff\&BT&IJI  9 ,Fii'OO#I  %%rFc"\rSrSrSrSSjrSrg)rSiaA stain normalizer implementation based on Vahadane's method for histopathology images. This class implements the "Structure-Preserving Color Normalization and Sparse Stain Separation for Histological Images" method proposed by Vahadane et al. The technique uses Non-negative Matrix Factorization (NMF) to separate Hematoxylin and Eosin (H&E) stains in histopathology images and then normalizes them to a target standard. The Vahadane method is particularly effective for histology image normalization because: 1. It maintains tissue structure during color normalization 2. It performs sparse stain separation, reducing color bleeding 3. It adaptively estimates stain vectors from each image 4. It preserves biologically relevant information This implementation uses SimpleNMF as its core matrix factorization algorithm to extract stain color vectors (appearance matrix) and concentration matrices from optical density-transformed images. It identifies the Hematoxylin and Eosin stains by their characteristic color profiles and spatial distribution. References: Vahadane, et al., 2016: Structure-preserving color normalization and sparse stain separation for histological images. IEEE transactions on medical imaging, 35(8), pp.1962-1971. Examples: >>> import numpy as np >>> import albumentations as A >>> from albumentations.augmentations.pixel import functional as F >>> import cv2 >>> >>> # Load source and target images (H&E stained histopathology) >>> source_img = cv2.imread('source_image.png') >>> source_img = cv2.cvtColor(source_img, cv2.COLOR_BGR2RGB) >>> target_img = cv2.imread('target_image.png') >>> target_img = cv2.cvtColor(target_img, cv2.COLOR_BGR2RGB) >>> >>> # Create and fit the normalizer to the target image >>> normalizer = F.VahadaneNormalizer() >>> normalizer.fit(target_img) >>> >>> # Normalize the source image to match the target's stain characteristics >>> normalized_img = normalizer.transform(source_img) c[U5n[SS9nURU5upE[U5upg[R "XVXW/5Ulg)zFit the Vahadane stain normalizer to an image. This function fits the Vahadane stain normalizer to an image. Args: img (np.ndarray): Input image. r)rlN)rIrjrrr1rJrY)rZr:rpnmfrrqrrs rDr_VahadaneNormalizer.fits[15s#++O<&;<%H"#%88-' $  rFrXNrb)rcrdrerfrgr_rhrrFrDrSrSs *X rFrScB^\rSrSrSrSSU4SjjjrSSSjjrSrU=r$) rTi!z5Macenko stain normalizer with optimized computations.c.>[TU]5 Xlgr)superr[angular_percentile)rZr __class__s rDr[MacenkoNormalizer.__init__$s "4rFc P[U5nSnX4:RSS9nX5n[U5S:a[SUS35e[R "U[R S9n[R"US[R[R-[R-5Sn[R"U5SSup[R"UR55S Sn [R "U SS2U 4[R S9n S n [R"[R"U 5U :5(aI[R "[R"U 5U :[R "U S:U *U 5U 5n Xl-n X-n[R""USS2S4USS2S45n[R$"US U- 5n[R$"X5n[R&"U5[R("U5nn[R&"U5[R("U5nn[R*"UU/UU//[R S9n[R "U R,[R S9n[R."UUSSS5n[R"U5nU[R0"[R2"US -SS S9U -5- nUSUS:aUUlgUSSS2Ulg)zFit the Macenko stain normalizer to an image. This function fits the Macenko stain normalizer to an image. Args: img (np.ndarray): Input image. angular_percentile (float): Angular percentile. g?rHrz"No tissue pixels found (threshold=)r'Nrr#g:0yE>rr$TrKr)rHrrI)rIrrrNrzr1rrr,calcCovarMatrix COVAR_NORMAL COVAR_ROWS COVAR_SCALEeigenrrfrrQry percentilerIrKrJrgemmrNrhrY)rZr:rrp od_thresholdthreshold_masktissue_density od_covariance eigenvalues eigenvectorsrprincipal_eigenvectorsepsilonsafe_tissue_densityplane_coordinates polar_angleshematoxylin_angle eosin_anglehem_coshem_sineos_coseos_sinangle_to_vectorprincipal_eigenvectors_t stain_vectorss rDr_MacenkoNormalizer.fit(s15 )8==1=E(8 ~  "A,qQR R--nBJJO++     s~~ - ?   %(IIm$P8PQmmLE 66"34bff=N6O66+.{0C((w '7!3 4**  $#78N8P8PXZXbXb#c   $   }- &}a7GaZ^0_bi0i(jj 5B$4G-X\J]4]= cpqusuqucv rF)rrY)c)rr)r:rrrrra) rcrdrerfrgr[r_rh __classcell__)rs@rDrTrT!s?55UwUwrFrTc`USS-USS--USS--nX!:nURS5$)zGet tissue mask from image. Args: img (np.ndarray): Input image threshold (float): Threshold for tissue detection. Default: 0.85 Returns: np.ndarray: Binary mask where True indicates tissue regions rgA`"?rgbX9?rgv/?rI)r)r:rR luminosityr^s rDget_tissue_maskrsGVu$s6{U'::S[5=PPJ  !D << rFc[U5n[R"U[RS9nSnXR-U[R "S5--nXR-n[R RXx5Rn U(d'[U5RS5n XU-U-X'OX-U-n X-n [R"U *5n U RUR5$![R Ra9 [R RURUUS9SRn Nf=f)aApply HE stain augmentation to an image. This function applies HE stain augmentation to an image. Args: img (np.ndarray): Input image. stain_matrix (np.ndarray): Stain matrix. scale_factors (np.ndarray): Scale factors. shift_values (np.ndarray): Shift values. augment_background (bool): Whether to augment the background. Returns: np.ndarray: Augmented image. r'rLr$)rcondrrI)rIr1rrrrrsolve LinAlgErrorlstsqrrrrM) r: stain_matrix scale_factors shift_valuesaugment_backgroundrpregularizationstain_correlationdensity_projectionrs tissue_maskoptical_density_result rgb_results rDapply_he_stain_augmentationrsB2-S1O'' BJJGLN$~~5PQ8RR%(9(99 !yy/@UWW %c*2226 ,@,MP],]`l,l) 4ClR2@//0J   cii ((+ 99 !yy NN   /   Q s()C<rs# $ 2GF ;E ;E;E;E ;E  ;E ;E| : :> 1  1h * *( "  "  " " "" " #!% < < < < <  < <~ - - - - - -` 5 5%55 5( ,4 ,4,4$,4 ,4 ,4^ ,5 ,5 ,5),5 ,5 ,5^ H6 H6H6H6 H6 H6V&&)&#&0 j jjj j  j  j jZ < < << < % <  <"<<< <~aaaa* a  a2 /0 /0/0/02 /0 % /0  /0  /0d \ \%\\ \  \  \ \~ v> v>!v>v>$ v>  v>  v>  v>r + +#++ + +\ 6  600$, Q T * .5 .5.5.5* .5  .5  .5b1. 8  8D M M(3D! H 'Y 'YT0B 0B0B 0B0Bj !7777: S S SS S  S SB" F/  F/R00,II6 ` ` ` ` ` `8000 Mk MkMk$Mk Mk  Mk  Mk Mk` 1 1 1 1  1  1  1  1h3 333 33&  )   )  2  2" =C =C!=C$=C# =C % =C  =C=C  =C@ "      4 ' ' ' '  '  '  ' ' ' ' ' ' ' ' ( (!" (#$)(((((((36  '  '  '  '   '   '   '  '  '  '  '  '  (  (  (  (! " (# $)(((((/ 95735p ; ;; '; ; ;|  *  *& C CCC C  CL C C C*C C CB! ! !! !@SUASU<SU SU " SU  SU  SU*SUSUlA    *   @PAP P P P * P  P2:A: : : : * :  :D!: !: !:*!: !:H"3 "3 "3*"3 "3JE E E*E E.% % %*% %6!A! ! ! ! * !  !H ) ) ))  )  ) )>I III I8 **  **  >!>>*> >B  - --- -  -  -` & &&& & &63l , ,> /+ /+/+ /+ /+ /+d 1% 1%1% 1%  1%  1% 1%h ; ; ; ; " ;  ; ;|1 111 1 " 1  1h7(t'; ';';';* ';  ';T44 4*4 4:P P 6P*P P@9KK KK K\KK KK  K  K * KK`xx * *  xx $ $      XX    xx    xx    HH     XX   W1h!!&  Q""$S2S2l&DC C L\w\w~(  9) 9)9)9) 9)  9)  9)  9)x  "  rF