careamics 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

careamics/config/configuration_model.py

@@ -9,11 +9,11 @@ from typing import Literal, Union
 
 import yaml
 from bioimageio.spec.generic.v0_3 import CiteEntry
-from pydantic import BaseModel, ConfigDict, field_validator, model_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 from typing_extensions import Self
 
-from .algorithm_model import AlgorithmConfig
 from .data_model import DataConfig
+from .fcn_algorithm_model import FCNAlgorithmConfig
 from .references import (
     CARE,
     CUSTOM,
@@ -39,6 +39,7 @@ from .training_model import TrainingConfig
 from .transformations.n2v_manipulate_model import (
     N2VManipulateModel,
 )
+from .vae_algorithm_model import VAEAlgorithmConfig
 
 
 class Configuration(BaseModel):
@@ -155,7 +156,9 @@ class Configuration(BaseModel):
     """Name of the experiment, used to name logs and checkpoints."""
 
     # Sub-configurations
-    algorithm_config: AlgorithmConfig
+    algorithm_config: Union[FCNAlgorithmConfig, VAEAlgorithmConfig] = Field(
+        discriminator="algorithm"
+    )
     """Algorithm configuration, holding all parameters required to configure the
     model."""
 

careamics/config/data_model.py

@@ -5,31 +5,44 @@ from __future__ import annotations
 from pprint import pformat
 from typing import Any, Literal, Optional, Union
 
+import numpy as np
 from numpy.typing import NDArray
 from pydantic import (
     BaseModel,
     ConfigDict,
-    Discriminator,
     Field,
+    PlainSerializer,
     field_validator,
     model_validator,
 )
 from typing_extensions import Annotated, Self
 
 from .support import SupportedTransform
-from .transformations.n2v_manipulate_model import N2VManipulateModel
-from .transformations.xy_flip_model import XYFlipModel
-from .transformations.xy_random_rotate90_model import XYRandomRotate90Model
+from .transformations import TRANSFORMS_UNION, N2VManipulateModel
 from .validators import check_axes_validity, patch_size_ge_than_8_power_of_2
 
-TRANSFORMS_UNION = Annotated[
-    Union[
-        XYFlipModel,
-        XYRandomRotate90Model,
-        N2VManipulateModel,
-    ],
-    Discriminator("name"),  # used to tell the different transform models apart
-]
+
+def np_float_to_scientific_str(x: float) -> str:
+    """Return a string scientific representation of a float.
+
+    In particular, this method is used to serialize floats to strings, allowing
+    numpy.float32 to be passed in the Pydantic model and written to a yaml file as str.
+
+    Parameters
+    ----------
+    x : float
+        Input value.
+
+    Returns
+    -------
+    str
+        Scientific string representation of the input value.
+    """
+    return np.format_float_scientific(x, precision=7)
+
+
+Float = Annotated[float, PlainSerializer(np_float_to_scientific_str, return_type=str)]
+"""Annotated float type, used to serialize floats to strings."""
 
 
 class DataConfig(BaseModel):
@@ -94,20 +107,20 @@ class DataConfig(BaseModel):
     """Batch size for training."""
 
     # Optional fields
-    image_means: Optional[list[float]] = Field(
+    image_means: Optional[list[Float]] = Field(
         default=None, min_length=0, max_length=32
     )
     """Means of the data across channels, used for normalization."""
 
-    image_stds: Optional[list[float]] = Field(default=None, min_length=0, max_length=32)
+    image_stds: Optional[list[Float]] = Field(default=None, min_length=0, max_length=32)
     """Standard deviations of the data across channels, used for normalization."""
 
-    target_means: Optional[list[float]] = Field(
+    target_means: Optional[list[Float]] = Field(
         default=None, min_length=0, max_length=32
     )
     """Means of the target data across channels, used for normalization."""
 
-    target_stds: Optional[list[float]] = Field(
+    target_stds: Optional[list[Float]] = Field(
         default=None, min_length=0, max_length=32
     )
     """Standard deviations of the target data across channels, used for
@@ -265,9 +278,7 @@ class DataConfig(BaseModel):
         elif (self.image_means is not None and self.image_stds is not None) and (
             len(self.image_means) != len(self.image_stds)
         ):
-            raise ValueError(
-                "Mean and std must be specified for each " "input channel."
-            )
+            raise ValueError("Mean and std must be specified for each input channel.")
 
         if (self.target_means and not self.target_stds) or (
             self.target_stds and not self.target_means
@@ -380,7 +391,7 @@ class DataConfig(BaseModel):
 
         Parameters
         ----------
-        image_means : numpy.ndarray ,tuple or list
+        image_means : numpy.ndarray, tuple or list
             Mean values for normalization.
         image_stds : numpy.ndarray, tuple or list
             Standard deviation values for normalization.

careamics/config/{algorithm_model.py → fcn_algorithm_model.py}

@@ -1,6 +1,4 @@
-"""Algorithm configuration."""
-
-from __future__ import annotations
+"""Module containing `FCNAlgorithmConfig` class."""
 
 from pprint import pformat
 from typing import Literal, Union
@@ -8,11 +6,11 @@ from typing import Literal, Union
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 from typing_extensions import Self
 
-from .architectures import CustomModel, UNetModel, VAEModel
-from .optimizer_models import LrSchedulerModel, OptimizerModel
+from careamics.config.architectures import CustomModel, UNetModel
+from careamics.config.optimizer_models import LrSchedulerModel, OptimizerModel
 
 
-class AlgorithmConfig(BaseModel):
+class FCNAlgorithmConfig(BaseModel):
     """Algorithm configuration.
 
     This Pydantic model validates the parameters governing the components of the
@@ -26,11 +24,11 @@ class AlgorithmConfig(BaseModel):
 
     Attributes
     ----------
-    algorithm : Literal["n2v", "custom"]
+    algorithm : {"n2v", "care", "n2n", "custom"}
         Algorithm to use.
-    loss : Literal["n2v", "mae", "mse"]
+    loss : {"n2v", "mae", "mse"}
         Loss function to use.
-    model : Union[UNetModel, VAEModel, CustomModel]
+    model : UNetModel or CustomModel
         Model architecture to use.
     optimizer : OptimizerModel, optional
         Optimizer to use.
@@ -47,7 +45,7 @@ class AlgorithmConfig(BaseModel):
     Examples
     --------
     Minimum example:
-    >>> from careamics.config import AlgorithmConfig
+    >>> from careamics.config import FCNAlgorithmConfig
     >>> config_dict = {
     ...     "algorithm": "n2v",
     ...     "loss": "n2v",
@@ -55,58 +53,37 @@ class AlgorithmConfig(BaseModel):
     ...         "architecture": "UNet",
     ...     }
     ... }
-    >>> config = AlgorithmConfig(**config_dict)
-
-    Using a custom model:
-    >>> from torch import nn, ones
-    >>> from careamics.config import AlgorithmConfig, register_model
-    ...
-    >>> @register_model(name="linear_model")
-    ... class LinearModel(nn.Module):
-    ...    def __init__(self, in_features, out_features, *args, **kwargs):
-    ...        super().__init__()
-    ...        self.in_features = in_features
-    ...        self.out_features = out_features
-    ...        self.weight = nn.Parameter(ones(in_features, out_features))
-    ...        self.bias = nn.Parameter(ones(out_features))
-    ...    def forward(self, input):
-    ...        return (input @ self.weight) + self.bias
-    ...
-    >>> config_dict = {
-    ...     "algorithm": "custom",
-    ...     "loss": "mse",
-    ...     "model": {
-    ...         "architecture": "Custom",
-    ...         "name": "linear_model",
-    ...         "in_features": 10,
-    ...         "out_features": 5,
-    ...     }
-    ... }
-    >>> config = AlgorithmConfig(**config_dict)
+    >>> config = FCNAlgorithmConfig(**config_dict)
     """
 
     # Pydantic class configuration
     model_config = ConfigDict(
         protected_namespaces=(),  # allows to use model_* as a field name
         validate_assignment=True,
+        extra="allow",
     )
 
     # Mandatory fields
-    algorithm: Literal["n2v", "care", "n2n", "custom"]  # defined in SupportedAlgorithm
-    """Name of the algorithm, as defined in SupportedAlgorithm."""
+    algorithm: Literal["n2v", "care", "n2n", "custom"]
+    """Name of the algorithm, as defined in SupportedAlgorithm. Use `custom` for custom
+    model architecture."""
 
     loss: Literal["n2v", "mae", "mse"]
     """Loss function to use, as defined in SupportedLoss."""
 
-    model: Union[UNetModel, VAEModel, CustomModel] = Field(discriminator="architecture")
-    """Model architecture to use, defined in SupportedArchitecture."""
+    model: Union[UNetModel, CustomModel] = Field(discriminator="architecture")
+    """Model architecture to use, along with its parameters. Compatible architectures
+    are defined in SupportedArchitecture, and their Pydantic models in
+    `careamics.config.architectures`."""
+    # TODO supported architectures are now all the architectures but does not warn users
+    # of the compatibility with the algorithm
 
     # Optional fields
     optimizer: OptimizerModel = OptimizerModel()
     """Optimizer to use, defined in SupportedOptimizer."""
 
     lr_scheduler: LrSchedulerModel = LrSchedulerModel()
-    """Learning rate scheduler to use, defined in SupportedScheduler."""
+    """Learning rate scheduler to use, defined in SupportedLrScheduler."""
 
     @model_validator(mode="after")
     def algorithm_cross_validation(self: Self) -> Self:
@@ -146,8 +123,10 @@ class AlgorithmConfig(BaseModel):
             if self.loss == "n2v":
                 raise ValueError("Supervised algorithms do not support loss `n2v`.")
 
-        if isinstance(self.model, VAEModel):
-            raise ValueError("VAE are currently not implemented.")
+        if (self.algorithm == "custom") != (self.model.architecture == "custom"):
+            raise ValueError(
+                "Algorithm and model architecture must be both `custom` or not."
+            )
 
         return self
 
@@ -160,3 +139,14 @@ class AlgorithmConfig(BaseModel):
             Pretty string.
         """
         return pformat(self.model_dump())
+
+    @classmethod
+    def get_compatible_algorithms(cls) -> list[str]:
+        """Get the list of compatible algorithms.
+
+        Returns
+        -------
+        list of str
+            List of compatible algorithms.
+        """
+        return ["n2v", "care", "n2n"]

careamics/config/likelihood_model.py

@@ -0,0 +1,60 @@
+"""Likelihood model."""
+
+from typing import Literal, Optional, Union
+
+import numpy as np
+import torch
+from pydantic import BaseModel, ConfigDict, Field, PlainSerializer, PlainValidator
+from typing_extensions import Annotated
+
+from careamics.models.lvae.noise_models import (
+    GaussianMixtureNoiseModel,
+    MultiChannelNoiseModel,
+)
+from careamics.utils.serializers import _array_to_json, _to_torch
+
+NoiseModel = Union[GaussianMixtureNoiseModel, MultiChannelNoiseModel]
+
+# TODO: this is a temporary solution to serialize and deserialize tensor fields
+# in pydantic models. Specifically, the aim is to enable saving and loading configs
+# with such tensors to/from JSON files during, resp., training and evaluation.
+Tensor = Annotated[
+    Union[np.ndarray, torch.Tensor],
+    PlainSerializer(_array_to_json, return_type=str),
+    PlainValidator(_to_torch),
+]
+"""Annotated tensor type, used to serialize arrays or tensors to JSON strings
+and deserialize them back to tensors."""
+
+
+class GaussianLikelihoodConfig(BaseModel):
+    """Gaussian likelihood configuration."""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    predict_logvar: Optional[Literal["pixelwise"]] = None
+    """If `pixelwise`, log-variance is computed for each pixel, else log-variance
+    is not computed."""
+
+    logvar_lowerbound: Union[float, None] = None
+    """The lowerbound value for log-variance."""
+
+
+class NMLikelihoodConfig(BaseModel):
+    """Noise model likelihood configuration."""
+
+    model_config = ConfigDict(validate_assignment=True, arbitrary_types_allowed=True)
+
+    # TODO remove and use as parameters to the likelihood functions?
+    data_mean: Tensor = torch.zeros(1)
+    """The mean of the data, used to unnormalize data for noise model evaluation.
+    Shape is (target_ch,) (or (1, target_ch, [1], 1, 1))."""
+
+    # TODO remove and use as parameters to the likelihood functions?
+    data_std: Tensor = torch.ones(1)
+    """The standard deviation of the data, used to unnormalize data for noise
+    model evaluation. Shape is (target_ch,) (or (1, target_ch, [1], 1, 1))."""
+
+    # TODO: serialization/deserialization for this
+    noise_model: Optional[NoiseModel] = Field(default=None, exclude=True)
+    """The noise model instance used to compute the likelihood."""

careamics/config/nm_model.py

@@ -0,0 +1,127 @@
+"""Noise models config."""
+
+from pathlib import Path
+from typing import Literal, Optional, Union
+
+import numpy as np
+import torch
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    PlainSerializer,
+    PlainValidator,
+    model_validator,
+)
+from typing_extensions import Annotated, Self
+
+from careamics.utils.serializers import _array_to_json, _to_numpy
+
+# TODO: this is a temporary solution to serialize and deserialize array fields
+# in pydantic models. Specifically, the aim is to enable saving and loading configs
+# with such arrays to/from JSON files during, resp., training and evaluation.
+Array = Annotated[
+    Union[np.ndarray, torch.Tensor],
+    PlainSerializer(_array_to_json, return_type=str),
+    PlainValidator(_to_numpy),
+]
+"""Annotated array type, used to serialize arrays or tensors to JSON strings
+and deserialize them back to arrays."""
+
+
+# TODO: add histogram-based noise model
+
+
+class GaussianMixtureNMConfig(BaseModel):
+    """Gaussian mixture noise model."""
+
+    model_config = ConfigDict(
+        protected_namespaces=(),
+        validate_assignment=True,
+        arbitrary_types_allowed=True,
+        extra="allow",
+    )
+    # model type
+    model_type: Literal["GaussianMixtureNoiseModel"]
+
+    path: Optional[Union[Path, str]] = None
+    """Path to the directory where the trained noise model (*.npz) is saved in the
+    `train` method."""
+
+    # TODO remove and use as parameters to the NM functions?
+    signal: Optional[Union[str, Path, np.ndarray]] = Field(default=None, exclude=True)
+    """Path to the file containing signal or respective numpy array."""
+
+    # TODO remove and use as parameters to the NM functions?
+    observation: Optional[Union[str, Path, np.ndarray]] = Field(
+        default=None, exclude=True
+    )
+    """Path to the file containing observation or respective numpy array."""
+
+    weight: Optional[Array] = None
+    """A [3*n_gaussian, n_coeff] sized array containing the values of the weights
+    describing the GMM noise model, with each row corresponding to one
+    parameter of each gaussian, namely [mean, standard deviation and weight].
+    Specifically, rows are organized as follows:
+    - first n_gaussian rows correspond to the means
+    - next n_gaussian rows correspond to the weights
+    - last n_gaussian rows correspond to the standard deviations
+    If `weight=None`, the weight array is initialized using the `min_signal`
+    and `max_signal` parameters."""
+
+    n_gaussian: int = Field(default=1, ge=1)
+    """Number of gaussians used for the GMM."""
+
+    n_coeff: int = Field(default=2, ge=2)
+    """Number of coefficients to describe the functional relationship between gaussian
+    parameters and the signal. 2 implies a linear relationship, 3 implies a quadratic
+    relationship and so on."""
+
+    min_signal: float = Field(default=0.0, ge=0.0)
+    """Minimum signal intensity expected in the image."""
+
+    max_signal: float = Field(default=1.0, ge=0.0)
+    """Maximum signal intensity expected in the image."""
+
+    min_sigma: float = Field(default=200.0, ge=0.0)  # TODO took from nb in pn2v
+    """Minimum value of `standard deviation` allowed in the GMM.
+    All values of `standard deviation` below this are clamped to this value."""
+
+    tol: float = Field(default=1e-10)
+    """Tolerance used in the computation of the noise model likelihood."""
+
+    @model_validator(mode="after")
+    def validate_path_to_pretrained_vs_training_data(self: Self) -> Self:
+        """Validate paths provided in the config.
+
+        Returns
+        -------
+        Self
+            Returns itself.
+        """
+        if self.path and (self.signal is not None or self.observation is not None):
+            raise ValueError(
+                "Either only 'path' to pre-trained noise model should be"
+                "provided or only signal and observation in form of paths"
+                "or numpy arrays."
+            )
+        if not self.path and (self.signal is None or self.observation is None):
+            raise ValueError(
+                "Either only 'path' to pre-trained noise model should be"
+                "provided or only signal and observation in form of paths"
+                "or numpy arrays."
+            )
+        return self
+
+
+# The noise model is given by a set of GMMs, one for each target
+# e.g., 2 target channels, 2 noise models
+class MultiChannelNMConfig(BaseModel):
+    """Noise Model config aggregating noise models for single output channels."""
+
+    # TODO: check that this model config is OK
+    model_config = ConfigDict(
+        validate_assignment=True, arbitrary_types_allowed=True, extra="allow"
+    )
+    noise_models: list[GaussianMixtureNMConfig]
+    """List of noise models, one for each target channel."""

careamics/config/optimizer_models.py

@@ -44,7 +44,9 @@ class OptimizerModel(BaseModel):
     )
 
     # Mandatory field
-    name: Literal["Adam", "SGD"] = Field(default="Adam", validate_default=True)
+    name: Literal["Adam", "SGD", "Adamax"] = Field(
+        default="Adam", validate_default=True
+    )
     """Name of the optimizer, supported optimizers are defined in SupportedOptimizer."""
 
     # Optional parameters, empty dict default value to allow filtering dictionary

careamics/config/support/supported_activations.py

@@ -24,3 +24,4 @@ class SupportedActivation(str, BaseEnum):
     TANH = "Tanh"
     RELU = "ReLU"
     LEAKYRELU = "LeakyReLU"
+    ELU = "ELU"

careamics/config/support/supported_algorithms.py

@@ -6,15 +6,28 @@ from careamics.utils import BaseEnum
 
 
 class SupportedAlgorithm(str, BaseEnum):
-    """Algorithms available in CAREamics.
-
-    # TODO
-    """
+    """Algorithms available in CAREamics."""
 
     N2V = "n2v"
+    """Noise2Void algorithm, a self-supervised approach based on blind denoising."""
+
     CARE = "care"
+    """Content-aware image restoration, a supervised algorithm used for a variety
+    of tasks."""
+
     N2N = "n2n"
+    """Noise2Noise algorithm, a self-supervised denoising scheme based on comparing
+    noisy images of the same sample."""
+
+    MUSPLIT = "musplit"
+    """An image splitting approach based on ladder VAE architectures."""
+
+    DENOISPLIT = "denoisplit"
+    """An image splitting and denoising approach based on ladder VAE architectures."""
+
     CUSTOM = "custom"
+    """Custom algorithm, used for cases where a custom architecture is provided."""
+
     # PN2V = "pn2v"
     # HDN = "hdn"
     # SEG = "segmentation"

careamics/config/support/supported_architectures.py

@@ -4,17 +4,14 @@ from careamics.utils import BaseEnum
 
 
 class SupportedArchitecture(str, BaseEnum):
-    """Supported architectures.
+    """Supported architectures."""
 
-    # TODO add details, in particular where to find the API for the models
+    UNET = "UNet"
+    """UNet architecture used with N2V, CARE and Noise2Noise."""
 
-    - UNet: classical UNet compatible with N2V2
-    - VAE: variational Autoencoder
-    - Custom: custom model registered with `@register_model` decorator
-    """
+    LVAE = "LVAE"
+    """Ladder Variational Autoencoder used for muSplit and denoiSplit."""
 
-    UNET = "UNet"
-    VAE = "VAE"
-    CUSTOM = (
-        "Custom"  # TODO all the others tags are small letters, except the architect
-    )
+    CUSTOM = "custom"
+    """Keyword used for custom architectures provided by users and only compatible
+    with `FCNAlgorithmConfig` configuration."""

careamics/config/support/supported_losses.py

@@ -22,6 +22,8 @@ class SupportedLoss(str, BaseEnum):
     N2V = "n2v"
     # PN2V = "pn2v"
     # HDN = "hdn"
+    MUSPLIT = "musplit"
+    DENOISPLIT = "denoisplit"
+    DENOISPLIT_MUSPLIT = "denoisplit_musplit"
     # CE = "ce"
     # DICE = "dice"
-    # CUSTOM = "custom" # TODO create mechanism for that

careamics/config/support/supported_optimizers.py

@@ -19,7 +19,7 @@ class SupportedOptimizer(str, BaseEnum):
     # Adagrad = "Adagrad"
     ADAM = "Adam"
     # AdamW = "AdamW"
-    # Adamax = "Adamax"
+    ADAMAX = "Adamax"
     # LBFGS = "LBFGS"
     # NAdam = "NAdam"
     # RAdam = "RAdam"

careamics/config/support/supported_transforms.py

@@ -9,3 +9,4 @@ class SupportedTransform(str, BaseEnum):
     XY_FLIP = "XYFlip"
     XY_RANDOM_ROTATE90 = "XYRandomRotate90"
     N2V_MANIPULATE = "N2VManipulate"
+    NORMALIZE = "Normalize"

careamics/config/training_model.py

@@ -3,13 +3,9 @@
 from __future__ import annotations
 
 from pprint import pformat
-from typing import Literal, Optional
+from typing import Literal, Optional, Union
 
-from pydantic import (
-    BaseModel,
-    ConfigDict,
-    Field,
-)
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from .callback_model import CheckpointModel, EarlyStoppingModel
 
@@ -37,6 +33,20 @@ class TrainingConfig(BaseModel):
     num_epochs: int = Field(default=20, ge=1)
     """Number of epochs, greater than 0."""
 
+    precision: Literal["64", "32", "16-mixed", "bf16-mixed"] = Field(default="32")
+    """Numerical precision"""
+    max_steps: int = Field(default=-1, ge=-1)
+    """Maximum number of steps to train for. -1 means no limit."""
+    check_val_every_n_epoch: int = Field(default=1, ge=1)
+    """Validation step frequency."""
+    enable_progress_bar: bool = Field(default=True)
+    """Whether to enable the progress bar."""
+    accumulate_grad_batches: int = Field(default=1, ge=1)
+    """Number of batches to accumulate gradients over before stepping the optimizer."""
+    gradient_clip_val: Optional[Union[int, float]] = None
+    """The value to which to clip the gradient"""
+    gradient_clip_algorithm: Literal["value", "norm"] = "norm"
+    """The algorithm to use for gradient clipping (see lightning `Trainer`)."""
     logger: Optional[Literal["wandb", "tensorboard"]] = None
     """Logger to use during training. If None, no logger will be used. Available
     loggers are defined in SupportedLogger."""
@@ -70,3 +80,22 @@ class TrainingConfig(BaseModel):
             Whether the logger is defined or not.
         """
         return self.logger is not None
+
+    @field_validator("max_steps")
+    @classmethod
+    def validate_max_steps(cls, max_steps: int) -> int:
+        """Validate the max_steps parameter.
+
+        Parameters
+        ----------
+        max_steps : int
+            Maximum number of steps to train for. -1 means no limit.
+
+        Returns
+        -------
+        int
+            Validated max_steps.
+        """
+        if max_steps == 0:
+            raise ValueError("max_steps must be greater than 0. Use -1 for no limit.")
+        return max_steps

careamics/config/transformations/__init__.py

@@ -5,11 +5,14 @@ __all__ = [
     "XYFlipModel",
     "NormalizeModel",
     "XYRandomRotate90Model",
-    "XorYFlipModel",
+    "TransformModel",
+    "TRANSFORMS_UNION",
 ]
 
 
 from .n2v_manipulate_model import N2VManipulateModel
 from .normalize_model import NormalizeModel
+from .transform_model import TransformModel
+from .transform_union import TRANSFORMS_UNION
 from .xy_flip_model import XYFlipModel
 from .xy_random_rotate90_model import XYRandomRotate90Model

careamics/config/transformations/n2v_manipulate_model.py

@@ -33,7 +33,7 @@ class N2VManipulateModel(TransformModel):
 
     name: Literal["N2VManipulate"] = "N2VManipulate"
     roi_size: int = Field(default=11, ge=3, le=21)
-    masked_pixel_percentage: float = Field(default=0.2, ge=0.05, le=1.0)
+    masked_pixel_percentage: float = Field(default=0.2, ge=0.05, le=10.0)
     strategy: Literal["uniform", "median"] = Field(default="uniform")
     struct_mask_axis: Literal["horizontal", "vertical", "none"] = Field(default="none")
     struct_mask_span: int = Field(default=5, ge=3, le=15)