
    h                        S r SSKJr  SSKJrJrJr  SSKrSSK	J
r
  SSKJr  SSKJr  SSKJr  SS	KJr  S
/r " S S
\5      rg)a  Implementation of XY masking for time-frequency domain transformations.

This module provides the XYMasking transform, which applies masking strips along the X and Y axes
of an image. This is particularly useful for audio spectrograms, time-series data visualizations,
and other grid-like data representations where masking in specific directions (time or frequency)
can improve model robustness and generalization.
    )annotations)AnyLiteralcastN)model_validator)Self)BaseDropout)NonNegativeIntRangeType)BaseTransformInitSchema	XYMaskingc                     ^  \ rS rSrSr " S S\5      r       S             SU 4S jjjr        SS jr      SS jr	SS jr
          SS	 jrS
rU =r$ )r      a	  Applies masking strips to an image, either horizontally (X axis) or vertically (Y axis),
simulating occlusions. This transform is useful for training models to recognize images
with varied visibility conditions. It's particularly effective for spectrogram images,
allowing spectral and frequency masking to improve model robustness.

At least one of `max_x_length` or `max_y_length` must be specified, dictating the mask's
maximum size along each axis.

Args:
    num_masks_x (int | tuple[int, int]): Number or range of horizontal regions to mask. Defaults to 0.
    num_masks_y (int | tuple[int, int]): Number or range of vertical regions to mask. Defaults to 0.
    mask_x_length (int | tuple[int, int]): Specifies the length of the masks along
        the X (horizontal) axis. If an integer is provided, it sets a fixed mask length.
        If a tuple of two integers (min, max) is provided,
        the mask length is randomly chosen within this range for each mask.
        This allows for variable-length masks in the horizontal direction.
    mask_y_length (int | tuple[int, int]): Specifies the height of the masks along
        the Y (vertical) axis. Similar to `mask_x_length`, an integer sets a fixed mask height,
        while a tuple (min, max) allows for variable-height masks, chosen randomly
        within the specified range for each mask. This flexibility facilitates creating masks of various
        sizes in the vertical direction.
    fill (tuple[float, float] | float | Literal["random", "random_uniform", "inpaint_telea", "inpaint_ns"]):
        Value for the dropped pixels. Can be:
        - int or float: all channels are filled with this value
        - tuple: tuple of values for each channel
        - 'random': each pixel is filled with random values
        - 'random_uniform': each hole is filled with a single random color
        - 'inpaint_telea': uses OpenCV Telea inpainting method
        - 'inpaint_ns': uses OpenCV Navier-Stokes inpainting method
        Default: 0
    fill_mask (tuple[float, float] | float | None): Fill value for dropout regions in the mask.
        If None, mask regions corresponding to image dropouts are unchanged. Default: None
    p (float): Probability of applying the transform. Defaults to 0.5.

Targets:
    image, mask, bboxes, keypoints, volume, mask3d

Image types:
    uint8, float32

Note: Either `max_x_length` or `max_y_length` or both must be defined.

c                  n    \ rS rSr% S\S'   S\S'   S\S'   S\S'   S\S'   S	\S
'   \" SS9SS j5       rSrg)XYMasking.InitSchemaE   r
   num_masks_xnum_masks_ymask_x_lengthmask_y_length^tuple[float, ...] | float | Literal['random', 'random_uniform', 'inpaint_telea', 'inpaint_ns']fill tuple[float, ...] | float | None	fill_maskafter)modec                    [        U R                  [        5      (       aL  U R                  S::  a<  [        U R                  [        5      (       a  U R                  S::  a  Sn[	        U5      eU $ )Nr   zOAt least one of `mask_x_length` or `mask_y_length` Should be a positive number.)
isinstancer   intr   
ValueError)selfmsgs     i/var/www/fran/franai/venv/lib/python3.13/site-packages/albumentations/augmentations/dropout/xy_masking.py_check_mask_length'XYMasking.InitSchema._check_mask_lengthN   sZ     4--s33&&!+t11377&&!+g o%K     N)returnr   )__name__
__module____qualname____firstlineno____annotations__r   r#   __static_attributes__r&   r%   r"   
InitSchemar   E   s=    ,,,,....ll33	g	&
	 
'
	r%   r.   c                   > [         TU ]  XuUS9  [        SU5      U l        [        SU5      U l        [        SU5      U l        [        SU5      U l        g )N)pr   r   tuple[int, int])super__init__r   r   r   r   r   )	r    r   r   r   r   r   r   r0   	__class__s	           r"   r3   XYMasking.__init__[   sW     	19= 1;? 1;?!"3]C!"3]Cr%   c           	         Ubd  [        U[        [        45      (       a'  US   S:  d	  US   U:  a  [        U SU SU S35      egUS:  d  X:  a  [        U SU SU SU 35      egg)	zHValidate the mask length against the corresponding image dimension size.Nr      z range z is out of valid range [0, ] z exceeds image )r   tuplelistr   )r    mask_lengthdimension_sizedimension_names       r"   _validate_mask_lengthXYMasking._validate_mask_lengthl   s     "+t}55q>A%Q.)H$)*'+>YZhYiijk  *I qK$@ N#31[MQ_P``abpaq!rss %A #r%   c                   US   SS nUu  pEU R                  U R                  US5        U R                  U R                  US5        U R                  U R                  X0R                  SS9nU R                  U R
                  X0R                  SS9n[        R                  " Xg-   5      nXR                  R                  S	S
5      S.$ )zGet parameters dependent on the data.

Args:
    params (dict[str, Any]): Dictionary containing parameters.
    data (dict[str, Any]): Dictionary containing data.

Returns:
    dict[str, np.ndarray]: Dictionary with parameters for transformation.

shapeN   r   r   x)axisyr   l    )holesseed)
r?   r   r   _generate_masksr   r   nparrayrandom_generatorintegers)	r    paramsdataimage_shapeheightwidthmasks_xmasks_yrG   s	            r"   get_params_dependent_on_data&XYMasking.get_params_dependent_on_data|   s     Wobq)#""4#5#5uoN""4#5#5vO&&t'7'7FXFX_b&c&&t'7'7FXFX_b&c*+(=(=(F(Fq)(TUUr%   c                4    U R                   R                  " U6 $ )N)	py_randomrandint)r    r<   s     r"   _generate_mask_sizeXYMasking._generate_mask_size   s    ~~%%{33r%   c                   Ub'  US:X  d!  [        U[        [        45      (       a  US:X  a  / $ / n[        U[        5      (       a  UO!U R                  R	                  US   US   5      nUu  px[        U5       Hx  n	U R                  U5      n
US:X  a&  U R                  R	                  SX-
  5      nSnX-   UpO%U R                  R	                  SXz-
  5      nSnXU
-   pUR                  XX45        Mz     U$ )Nr   r7   rD   )r   r   floatrX   rY   rangerZ   append)r    	num_masksrP   
max_lengthrE   masksnum_masks_integerrQ   rR   _lengthx_miny_minx_maxy_maxs                  r"   rI   XYMasking._generate_masks   s     qZ	CQV<5X5X]fjk]kI#Is33I9O9OPYZ[P\^ghi^j9k 	 $()A--j9Fs{..q%.A$~vu..q&/B$fnuLL%56 * r%   )r   r   r   r   )r   r   r   r   r   Ng      ?)r   tuple[int, int] | intr   rk   r   rk   r   rk   r   r   r   r   r0   r]   )r<   tuple[int, int] | Noner=   r   r>   strr'   None)rN   dict[str, Any]rO   ro   r'   zdict[str, np.ndarray])r<   r1   r'   r   )
r`   r1   rP   r1   ra   rl   rE   rm   r'   zlist[tuple[int, int, int, int]])r(   r)   r*   r+   __doc__r   r.   r3   r?   rU   rZ   rI   r-   __classcell__)r4   s   @r"   r   r      s   *X, 0 ./-./0/0op6:D*D +D -	D
 -D mD 4D D D"t+t t 	t
 
t VV V 
	V:4" % +	
  
) r%   )rp   
__future__r   typingr   r   r   numpyrJ   pydanticr   typing_extensionsr   /albumentations.augmentations.dropout.transformsr	   albumentations.core.pydanticr
   (albumentations.core.transforms_interfacer   __all__r   r&   r%   r"   <module>r{      s<    # % %  $ " G @ L-b br%   