phenotypic.enhance

Image enhancers to boost fungal colonies on agar backgrounds.

Preprocessing steps that denoise, normalize, and emphasize colony structure before detection. The module covers local contrast equalization (EnhanceLocalContrast), Gaussian/median/rank denoising, rolling-ball and Gaussian background subtraction, tophat and Laplacian edge accentuation, Sobel gradients, contrast stretching, unsharp masking, bilateral denoising, BM3D denoising, Hessian-based ridge detection (Frangi vesselness, Sato tubeness, Meijering neuriteness, Hessian filter) for filamentous structure detection, morphological operations (opening, closing, erosion, dilation, gradient, black tophat) for noise removal and boundary enhancement, and more for clean plates. All operate on copies of the grayscale view to keep raw data intact.

Classes

BayesShrinkEnhancer	Denoise detect_mat with adaptive per-subband BayesShrink wavelet thresholding.
LocalEdgeDenoise	Denoise detect_mat with local edge-preserving bilateral filtering.
EnhanceBlockMatch	Denoise detect_mat using block-matching and 3-D collaborative filtering.
EnhanceLocalContrast	Boost local contrast in detect_mat using adaptive histogram equalization.
StructureSmoothing	Enhance filamentous structures in detect_mat via coherence-enhancing anisotropic diffusion.
ContrastStretching	Stretch the intensity range of detect_mat to fill the full dynamic range.
FocusEdgeFrangi	Enhance elongated structures in detect_mat using multi-scale Frangi vesselness filtering.
GaussianBlur	Smooth noise in detect_mat using isotropic Gaussian convolution.
SubtractGaussian	Remove background from detect_mat by subtracting a Gaussian-blurred estimate.
GrayOpening	Remove small bright artefacts from detect_mat via morphological opening.
FocusEdgeHessian	Enhance colony boundaries and ridge-like structures via multi-scale Hessian filtering.
FlattenIllumination	Correct uneven illumination in detect_mat using homomorphic frequency-domain filtering.
ImageInverter	Invert detect_mat pixel intensities so dark colonies become bright.
FocusEdgeLaplace	Enhance colony edges in detect_mat with a discrete Laplacian operator.
MedianFilter	Remove impulsive noise from detect_mat while preserving colony edges.
FocusEdgeMeijering	Enhance fine filamentous ridges in detect_mat using the Meijering neuriteness filter.
FocusBlobLoG	Enhance blob-like colonies in detect_mat with scale-normalised Laplacian of Gaussian.
NonLocalMeansDenoiser	Denoise detect_mat with non-local means patch-based filtering.
SubtractOpening	Subtract background from detect_mat via OpenCV-accelerated morphological opening.
FocusEdgePhase	Enhance colony edges in detect_mat using contrast-invariant phase congruency.
RankMedianEnhancer	Suppress impulsive noise in detect_mat with rank-based median filtering.
SubtractRollingBall	Remove background from detect_mat with ImageJ-style rolling-ball subtraction.
FocusEdgeSato	Enhance hyphal ridges and tubular colony structures in detect_mat using the Sato tubeness filter.
FocusEdgeSobel	Highlight colony edges in detect_mat using the Sobel gradient operator.
SharpenEdgeGauss	Sharpen colony edges in detect_mat with unsharp masking.
VisuShrinkEnhancer	Denoise detect_mat with universal VisuShrink wavelet thresholding.
WhiteTophatEnhance	Isolate small bright structures in detect_mat with the white top-hat transform.
SubtractWhiteTophat	Suppress small bright artifacts in detect_mat by subtracting the white top-hat.
SetDetectMode	Switch the detection matrix source channel mid-pipeline.

class phenotypic.enhance.BayesShrinkEnhancer(*, use_gat: bool = False, gat_gain: Annotated[float, Gt(gt=0)] = 1.0, gat_mu: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0.0, gat_read_sigma: Annotated[float, Ge(ge=0)] = 0.0, gat_scale_factor: Annotated[float | None, Gt(gt=0)] = None, sigma: float | None = None, wavelet: str = 'db2', mode: Literal['soft', 'hard'] = 'soft', wavelet_levels: Annotated[int | None, TuneSpec(low=2, high=6, step=None, log=False, categories=None, tunable=True)] = None, clip: bool = True, rescale_sigma: bool = True)

Bases: _GATSupportMixin, ImageDenoiser

Denoise detect_mat with adaptive per-subband BayesShrink wavelet thresholding.

Decomposes the detection matrix into wavelet subbands and applies a separate soft-threshold to each, computed from the estimated signal and noise variances. This preserves colony texture more faithfully than a universal threshold while suppressing scanner and camera noise. For algorithm details see What Enhancement Actually Does.

Best For:

• Flatbed scanner images where CCD read noise is spatially uniform and the auto-estimated sigma is reliable.

• Plates requiring fine colony texture retention before downstream morphology measurement or texture analysis.

• Pre-processing before ridge or edge enhancers that amplify noise alongside structure.

• Low-light fluorescence plate images with Poisson-dominated shot noise when use_gat=True is enabled.

• Pipelines where denoising must be fully serialisable and reproducible across runs.

Consider Also:

• VisuShrinkEnhancer when a single universal threshold across all subbands is preferred for speed or simplicity.

• EnhanceBlockMatch for structured scanner banding or systematic CCD patterned noise that wavelet thresholding does not fully remove.

• NonLocalMeansDenoiser when patch-based self-similarity in the agar or colony texture can be exploited.

• MedianFilter for salt-and-pepper impulse noise rather than Gaussian additive noise.

Parameters:

• sigma (float | None) – Noise standard deviation on the [0, 1] intensity scale used to compute per-subband BayesShrink thresholds. None (default) auto-estimates via the MAD of the finest-scale HH subband (median(|coeff|) / 0.6745). Typical manual override: 0.01–0.05 for moderate scanner noise. Raising sigma shrinks more coefficients and smooths more aggressively; lowering it retains more texture alongside residual noise. Ignored when use_gat=True — the stabilised-domain value 1.0 is used internally. Default: None.

• wavelet (str) – PyWavelets wavelet family string. Must be an orthogonal wavelet for BayesShrink’s variance-preservation property to hold. 'db2' (default) has compact support and handles colony edges well; 'db4' represents smoother signals more sparsely and may suit filamentous fungi hyphae. Accepted examples: 'db1'– 'db8', 'sym2'–'sym8'. Default: 'db2'.

• mode (Literal['soft', 'hard']) – Wavelet coefficient thresholding mode. 'soft' (default) shrinks each coefficient toward zero by the threshold amount, producing a smooth, ringing-free output consistent with BayesShrink’s Bayesian risk derivation. 'hard' zeros coefficients below the threshold and leaves those above unchanged; this can introduce pseudo-Gibbs artefacts near sharp colony edges. Default: 'soft'.

• wavelet_levels (Annotated[int | None, TuneSpec(low=2, high=6, step=None, log=False, categories=None, tunable=True)]) – Decomposition depth. None (default) uses max_possible_levels - 3, a conservative choice that avoids the coarsest subbands where reliable per-subband threshold estimation fails. Practical range: 2–8 integers; fewer than 3 leaves coarse-scale noise untouched; more than max - 3 risks over-smoothing broad colony texture. Default: None.

• clip (bool) – Clamp output to [0, 1] after reconstruction. Soft thresholding can produce values marginally outside [0, 1] due to floating-point accumulation. Default: True. Automatically set to False inside the GAT region when use_gat=True.

• rescale_sigma (bool) – Allow skimage to rescale sigma to match each subband’s energy (the statistically correct behaviour for orthonormal wavelets). Default: True. Automatically forced to False when use_gat=True because the stabilised domain has a different variance profile. Default: True.

• use_gat=True (# GAT parameters — only active when)

• use_gat (bool) – Wrap the denoise call in a forward Generalised Anscombe Transform (GAT) → denoise at fixed sigma=1.0 → exact unbiased inverse GAT pipeline. Enables correct denoising under mixed Poisson-Gaussian noise (e.g. fluorescence plate readers, low-light incubator cameras). Leave False for standard flatbed scanner images where additive Gaussian noise dominates. Default: False.

• gat_gain (Annotated[float, Gt(gt=0)]) – Camera gain in electrons per ADU, used by the GAT to model Poisson variance scaling. Obtain from the sensor datasheet or a photon-transfer curve. Only relevant when use_gat=True. Default: 1.0.

• gat_mu (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Read-noise mean (DC baseline offset) in ADU before [0, 1] normalisation. Set to the dark-current bias level if the image has not been background-subtracted. Only relevant when use_gat=True. Default: 0.0.

• gat_read_sigma (Annotated[float, Ge(ge=0)]) – Standard deviation of the Gaussian read-noise component (electrons RMS). Setting this to the manufacturer’s read noise improves stabilisation accuracy under mixed Poisson-Gaussian conditions. Only relevant when use_gat=True. Default: 0.0.

• gat_scale_factor (Annotated[float | None, Gt(gt=0)]) – Multiplier converting the [0, 1] normalised detect_mat back to photon counts before the forward GAT. None auto-detects from image.metadata.bit_depth (255 for 8-bit, 65535 for 16-bit). Only relevant when use_gat=True. Default: None.

Returns:

Input image with detect_mat denoised via adaptive wavelet thresholding. rgb and gray are unchanged.

Return type:

Image

References

[1] S. G. Chang, B. Yu, and M. Vetterli, “Adaptive wavelet thresholding for image denoising and compression,” IEEE Trans. Image Process., vol. 9, no. 9, pp. 1532–1546, Sep. 2000.

[2] D. L. Donoho and I. M. Johnstone, “Ideal spatial adaptation by wavelet shrinkage,” Biometrika, vol. 81, no. 3, pp. 425–455, Sep. 1994.

[3] M. Mäkitalo and A. Foi, “Optimal inversion of the generalized Anscombe transformation for Poisson-Gaussian noise,” IEEE Trans. Image Process., vol. 22, no. 1, pp. 91–103, Jan. 2013.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of enhancement pipelines on plate images. How To: Denoise Low-Light Images for guidance on choosing between BayesShrink, BM3D, and non-local means for low-light plates. What Enhancement Actually Does for background on wavelet denoising and threshold selection strategies.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

clip: bool

gat_gain: float

gat_mu: Annotated[float, TuneSpec(tunable=False)]

gat_read_sigma: float

gat_scale_factor: float | None

mode: Literal['soft', 'hard']

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'clip': FieldInfo(annotation=bool, required=False, default=True, description='Clamp output to [0, 1] after reconstruction. Soft thresholding can produce values marginally outside [0, 1] due to floating-point accumulation. Default: ``True``. Automatically set to ``False`` inside the GAT region when ``use_gat=True``.'), 'gat_gain': FieldInfo(annotation=float, required=False, default=1.0, description='Camera gain in electrons per ADU, used by the GAT to model Poisson variance scaling. Obtain from the sensor datasheet or a photon-transfer curve. Only relevant when ``use_gat=True``.', metadata=[Gt(gt=0)]), 'gat_mu': FieldInfo(annotation=float, required=False, default=0.0, description='Read-noise mean (DC baseline offset) in ADU before [0, 1] normalisation. Set to the dark-current bias level if the image has not been background-subtracted. Only relevant when ``use_gat=True``. Default: 0.0.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'gat_read_sigma': FieldInfo(annotation=float, required=False, default=0.0, description="Standard deviation of the Gaussian read-noise component (electrons RMS). Setting this to the manufacturer's read noise improves stabilisation accuracy under mixed Poisson-Gaussian conditions. Only relevant when ``use_gat=True``.", metadata=[Ge(ge=0)]), 'gat_scale_factor': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Multiplier converting the [0, 1] normalised ``detect_mat`` back to photon counts before the forward GAT. ``None`` auto-detects from ``image.metadata.bit_depth`` (255 for 8-bit, 65535 for 16-bit). Only relevant when ``use_gat=True``.', metadata=[Gt(gt=0)]), 'mode': FieldInfo(annotation=Literal['soft', 'hard'], required=False, default='soft', description="Wavelet coefficient thresholding mode. ``'soft'`` (default) shrinks each coefficient toward zero by the threshold amount, producing a smooth, ringing-free output consistent with BayesShrink's Bayesian risk derivation. ``'hard'`` zeros coefficients below the threshold and leaves those above unchanged; this can introduce pseudo-Gibbs artefacts near sharp colony edges."), 'rescale_sigma': FieldInfo(annotation=bool, required=False, default=True, description="Allow skimage to rescale ``sigma`` to match each subband's energy (the statistically correct behaviour for orthonormal wavelets). Default: ``True``. Automatically forced to ``False`` when ``use_gat=True`` because the stabilised domain has a different variance profile. Default: ``True``. # GAT parameters — only active when use_gat=True"), 'sigma': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Noise standard deviation on the [0, 1] intensity scale used to compute per-subband BayesShrink thresholds. ``None`` (default) auto-estimates via the MAD of the finest-scale HH subband (``median(|coeff|) / 0.6745``). Typical manual override: 0.01--0.05 for moderate scanner noise. Raising sigma shrinks more coefficients and smooths more aggressively; lowering it retains more texture alongside residual noise. Ignored when ``use_gat=True`` — the stabilised-domain value 1.0 is used internally. Default: ``None``.'), 'use_gat': FieldInfo(annotation=bool, required=False, default=False, description='Wrap the denoise call in a forward Generalised Anscombe Transform (GAT) → denoise at fixed sigma=1.0 → exact unbiased inverse GAT pipeline. Enables correct denoising under mixed Poisson-Gaussian noise (e.g. fluorescence plate readers, low-light incubator cameras). Leave ``False`` for standard flatbed scanner images where additive Gaussian noise dominates. Default: ``False``.'), 'wavelet': FieldInfo(annotation=str, required=False, default='db2', description="PyWavelets wavelet family string. Must be an orthogonal wavelet for BayesShrink's variance-preservation property to hold. ``'db2'`` (default) has compact support and handles colony edges well; ``'db4'`` represents smoother signals more sparsely and may suit filamentous fungi hyphae. Accepted examples: ``'db1'``-- ``'db8'``, ``'sym2'``--``'sym8'``. Default: ``'db2'``."), 'wavelet_levels': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Decomposition depth. ``None`` (default) uses ``max_possible_levels - 3``, a conservative choice that avoids the coarsest subbands where reliable per-subband threshold estimation fails. Practical range: 2--8 integers; fewer than 3 leaves coarse-scale noise untouched; more than ``max - 3`` risks over-smoothing broad colony texture. Default: ``None``.', metadata=[TuneSpec(low=2, high=6, step=None, log=False, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

rescale_sigma: bool

sigma: float | None

use_gat: bool

wavelet: str

wavelet_levels: Annotated[int | None, TuneSpec(2, 6)]

class phenotypic.enhance.ContrastStretching(*, lower_percentile: Annotated[int, TuneSpec(low=1, high=5, step=None, log=False, categories=None, tunable=True)] = 2, upper_percentile: Annotated[int, TuneSpec(low=95, high=99, step=None, log=False, categories=None, tunable=True)] = 98)

Bases: ContrastAdjustment

Stretch the intensity range of detect_mat to fill the full dynamic range.

Rescales pixel values by clipping at lower and upper percentiles, then linearly remapping the retained range to [0, 1]. Outliers such as specular highlights and deep shadows are clamped, expanding the range where colony intensities reside. Simpler and faster than EnhanceLocalContrast, with no local tile artefacts.

For how contrast adjustment fits into the pipeline, see What Enhancement Actually Does.

Best For:

• Plates with narrow intensity histograms from under-exposure or low scanner gain.

• Normalizing exposure variation across imaging sessions or plate batches.

• Quick preprocessing before global thresholding (Otsu, Triangle).

• Images with bright specular highlights or very dark border regions that compress the useful intensity range.

Consider Also:

• EnhanceLocalContrast when illumination varies spatially across the plate and per-tile equalization is needed.

• FlattenIllumination when the primary issue is a large-scale brightness gradient rather than a narrow dynamic range.

Parameters:

• lower_percentile (Annotated[int, TuneSpec(low=1, high=5, step=None, log=False, categories=None, tunable=True)]) – Dark clipping point. Pixels below this percentile are mapped to 0. Typical range: 1–5. Default: 2.

• upper_percentile (Annotated[int, TuneSpec(low=95, high=99, step=None, log=False, categories=None, tunable=True)]) – Bright clipping point. Pixels above this percentile are mapped to 1. Typical range: 95–99. Default: 98.

Returns:

Input image with detect_mat rescaled to the full dynamic range. rgb and gray are unchanged.

Return type:

Image

See also

How To: Enhance Low-Contrast Images for a comparison of contrast enhancement methods on real plate images. What Enhancement Actually Does for how enhancement fits into the pipeline model.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

lower_percentile: Annotated[int, TuneSpec(1, 5)]

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'lower_percentile': FieldInfo(annotation=int, required=False, default=2, description='Dark clipping point. Pixels below this percentile are mapped to 0. Typical range: 1--5. Default: 2.', metadata=[TuneSpec(low=1, high=5, step=None, log=False, categories=None, tunable=True)]), 'upper_percentile': FieldInfo(annotation=int, required=False, default=98, description='Bright clipping point. Pixels above this percentile are mapped to 1. Typical range: 95--99. Default: 98.', metadata=[TuneSpec(low=95, high=99, step=None, log=False, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

upper_percentile: Annotated[int, TuneSpec(95, 99)]

class phenotypic.enhance.EnhanceBlockMatch(*, use_gat: bool = False, gat_gain: Annotated[float, Gt(gt=0)] = 1.0, gat_mu: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0.0, gat_read_sigma: Annotated[float, Ge(ge=0)] = 0.0, gat_scale_factor: Annotated[float | None, Gt(gt=0)] = None, sigma_psd: Annotated[float, Ge(ge=0.0), TuneSpec(low=0.01, high=0.15, step=None, log=True, categories=None, tunable=True)] = 0.02, block_size: Annotated[int, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 8, stage_arg: Literal['all_stages', 'hard_thresholding'] = 'all_stages', clip: bool = True)

Bases: _GATSupportMixin, ImageDenoiser

Denoise detect_mat using block-matching and 3-D collaborative filtering.

Groups similar image patches across the plate and filters them jointly in a 3-D transform domain, removing scanner banding, CCD read patterns, and imaging-hardware texture while retaining colony edges and fine morphological features. The optional second Wiener-filtering stage further sharpens colony boundaries relative to the initial hard-thresholding pass. For algorithm details see What Enhancement Actually Does.

Best For:

• Structured patterned noise from scanner CCD rows or camera sensor banding visible across the plate background.

• Low-light incubator or plate-reader images where high ISO introduces spatially correlated noise.

• Plates where fine colony morphology — wrinkle texture, satellite colonies, rough biofilm edges — must survive denoising.

• Pipelines that already use 'all_stages' for highest-quality deliverables and can absorb the additional compute.

• Poisson-Gaussian mixed noise (fluorescence readers, sCMOS cameras) via use_gat=True.

Consider Also:

• BayesShrinkEnhancer for per-subband adaptive wavelet denoising with lower computational cost when structured patterns are not the primary concern.

• NonLocalMeansDenoiser for patch-based denoising at moderately lower computational overhead.

• VisuShrinkEnhancer when speed matters more than quality and a universal wavelet threshold is acceptable.

• MedianFilter for isolated salt-and-pepper impulse noise rather than Gaussian or structured noise.

Parameters:

• sigma_psd (Annotated[float, Ge(ge=0.0), TuneSpec(low=0.01, high=0.15, step=None, log=True, categories=None, tunable=True)]) – Noise standard deviation on the [0, 1] normalised intensity scale. Acts as the noise-model oracle for both the hard-thresholding and Wiener stages. Typical range: 0.01–0.05 for moderate scanner noise; 0.05–0.15 for heavy noise. Setting too low leaves structured patterns intact; too high smooths away colony texture alongside noise. Ignored when use_gat=True — the stabilised-domain value 1.0 is used internally. Default: 0.02.

• block_size (Annotated[int, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Side length (pixels) of square patches used for block-matching. Larger blocks capture more self-similar structure and increase denoising strength at the cost of speed and potential over-smoothing of fine colony detail. Typical range: 4–16; integer powers of 2 are conventional. Default: 8.

• stage_arg (Literal['all_stages', 'hard_thresholding']) – Processing pipeline. 'all_stages' (default) runs the hard-thresholding stage followed by a Wiener-filtering stage using the HT estimate as an oracle, producing better boundary sharpness. 'hard_thresholding' runs only the first stage — approximately 2× faster with slightly coarser colony edges. Accepted values: 'all_stages', 'hard_thresholding'. Default: 'all_stages'.

• clip (bool) – Clamp output to [0, 1] after BM3D aggregation. BM3D can produce values marginally outside [0, 1] due to weighted patch accumulation. Default: True. Automatically set to False inside the GAT region when use_gat=True.

• use_gat=True (# GAT parameters — only active when)

• use_gat (bool) – Wrap the BM3D call in a forward Generalised Anscombe Transform (GAT) → denoise at fixed sigma_psd=1.0 → exact unbiased inverse GAT pipeline. Enables correct denoising under mixed Poisson-Gaussian noise from low-light sensors. Leave False for standard flatbed scanner images where additive Gaussian read noise dominates. Default: False.

• gat_gain (Annotated[float, Gt(gt=0)]) – Camera gain in electrons per ADU, used by the GAT to model Poisson variance scaling. Obtain from the sensor datasheet or a photon-transfer curve. Only relevant when use_gat=True. Default: 1.0.

• gat_mu (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Read-noise mean (DC baseline offset) in ADU before [0, 1] normalisation. Set to the dark-current bias level if the image has not been background-subtracted. Only relevant when use_gat=True. Default: 0.0.

• gat_read_sigma (Annotated[float, Ge(ge=0)]) – Standard deviation of the Gaussian read-noise component (electrons RMS). Setting this to the manufacturer’s read noise improves stabilisation accuracy under mixed Poisson-Gaussian conditions. Only relevant when use_gat=True. Default: 0.0.

• gat_scale_factor (Annotated[float | None, Gt(gt=0)]) – Multiplier converting the [0, 1] normalised detect_mat back to photon counts before the forward GAT. None auto-detects from image.metadata.bit_depth (255 for 8-bit, 65535 for 16-bit). Supply an explicit value when the detect_mat was normalised by a range other than the bit-depth maximum. Only relevant when use_gat=True. Default: None.

Returns:

Input image with detect_mat denoised via BM3D collaborative filtering. rgb and gray are unchanged.

Return type:

Image

References

[1] K. Dabov, A. Foi, V. Katkovnik, and K. Egiazarian, “Image denoising by sparse 3-D transform-domain collaborative filtering,” IEEE Trans. Image Process., vol. 16, no. 8, pp. 2080–2095, Aug. 2007.

[2] M. Mäkitalo and A. Foi, “Optimal inversion of the generalized Anscombe transformation for Poisson-Gaussian noise,” IEEE Trans. Image Process., vol. 22, no. 1, pp. 91–103, Jan. 2013.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of denoising pipelines on plate images. How To: Denoise Low-Light Images for BM3D and other denoising strategies on low-light plate images. What Enhancement Actually Does for background on block-matching and collaborative filtering.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

block_size: Annotated[int, TuneSpec(tunable=False)]

clip: bool

gat_gain: float

gat_mu: Annotated[float, TuneSpec(tunable=False)]

gat_read_sigma: float

gat_scale_factor: float | None

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'block_size': FieldInfo(annotation=int, required=False, default=8, description='Side length (pixels) of square patches used for block-matching. Larger blocks capture more self-similar structure and increase denoising strength at the cost of speed and potential over-smoothing of fine colony detail. Typical range: 4--16; integer powers of 2 are conventional. Default: 8.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'clip': FieldInfo(annotation=bool, required=False, default=True, description='Clamp output to [0, 1] after BM3D aggregation. BM3D can produce values marginally outside [0, 1] due to weighted patch accumulation. Default: ``True``. Automatically set to ``False`` inside the GAT region when ``use_gat=True``. # GAT parameters — only active when use_gat=True'), 'gat_gain': FieldInfo(annotation=float, required=False, default=1.0, description='Camera gain in electrons per ADU, used by the GAT to model Poisson variance scaling. Obtain from the sensor datasheet or a photon-transfer curve. Only relevant when ``use_gat=True``.', metadata=[Gt(gt=0)]), 'gat_mu': FieldInfo(annotation=float, required=False, default=0.0, description='Read-noise mean (DC baseline offset) in ADU before [0, 1] normalisation. Set to the dark-current bias level if the image has not been background-subtracted. Only relevant when ``use_gat=True``. Default: 0.0.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'gat_read_sigma': FieldInfo(annotation=float, required=False, default=0.0, description="Standard deviation of the Gaussian read-noise component (electrons RMS). Setting this to the manufacturer's read noise improves stabilisation accuracy under mixed Poisson-Gaussian conditions. Only relevant when ``use_gat=True``.", metadata=[Ge(ge=0)]), 'gat_scale_factor': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Multiplier converting the [0, 1] normalised ``detect_mat`` back to photon counts before the forward GAT. ``None`` auto-detects from ``image.metadata.bit_depth`` (255 for 8-bit, 65535 for 16-bit). Supply an explicit value when the ``detect_mat`` was normalised by a range other than the bit-depth maximum. Only relevant when ``use_gat=True``. Default: ``None``.', metadata=[Gt(gt=0)]), 'sigma_psd': FieldInfo(annotation=float, required=False, default=0.02, description='Noise standard deviation on the [0, 1] normalised intensity scale. Acts as the noise-model oracle for both the hard-thresholding and Wiener stages. Typical range: 0.01--0.05 for moderate scanner noise; 0.05--0.15 for heavy noise. Setting too low leaves structured patterns intact; too high smooths away colony texture alongside noise. Ignored when ``use_gat=True`` — the stabilised-domain value 1.0 is used internally. Default: 0.02.', metadata=[Ge(ge=0.0), TuneSpec(low=0.01, high=0.15, step=None, log=True, categories=None, tunable=True)]), 'stage_arg': FieldInfo(annotation=Literal['all_stages', 'hard_thresholding'], required=False, default='all_stages', description="Processing pipeline. ``'all_stages'`` (default) runs the hard-thresholding stage followed by a Wiener-filtering stage using the HT estimate as an oracle, producing better boundary sharpness. ``'hard_thresholding'`` runs only the first stage — approximately 2× faster with slightly coarser colony edges. Accepted values: ``'all_stages'``, ``'hard_thresholding'``. Default: ``'all_stages'``."), 'use_gat': FieldInfo(annotation=bool, required=False, default=False, description='Wrap the BM3D call in a forward Generalised Anscombe Transform (GAT) → denoise at fixed sigma_psd=1.0 → exact unbiased inverse GAT pipeline. Enables correct denoising under mixed Poisson-Gaussian noise from low-light sensors. Leave ``False`` for standard flatbed scanner images where additive Gaussian read noise dominates. Default: ``False``.')}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

sigma_psd: Annotated[float, TuneSpec(0.01, 0.15, log=True)]

stage_arg: Literal['all_stages', 'hard_thresholding']

use_gat: bool

class phenotypic.enhance.EnhanceLocalContrast(*, kernel_size: Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, clip_limit: Annotated[float, TuneSpec(low=0.005, high=0.05, step=None, log=True, categories=None, tunable=True)] = 0.01)

Bases: ContrastAdjustment

Boost local contrast in detect_mat using adaptive histogram equalization.

Divides detect_mat into tiles and equalizes the intensity histogram within each tile, with a clip limit that caps the redistribution gain and prevents excessive noise amplification. Faint colonies become more visible and easier to threshold, even when illumination varies across the plate.

For a discussion of contrast enhancement strategies, see What Enhancement Actually Does.

Best For:

• Plates with faint or translucent colonies that blend into agar.

• Images with uneven illumination such as vignetting or shadows from plate lids.

• Pre-conditioning before global thresholding (Otsu, Triangle).

• Early time-point plates where colonies are barely visible.

Consider Also:

• ContrastStretching for a simpler global contrast adjustment when illumination is already uniform across the plate.

• FlattenIllumination when the primary problem is a large-scale illumination gradient rather than local contrast variation.

• SharpenEdgeGauss when edges need sharpening rather than contrast boosting.

Parameters:

• kernel_size (Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Tile size for local equalization in pixels. Smaller tiles reveal tiny colonies and local features but amplify agar texture; larger tiles produce smoother results. None auto-selects a tile size of roughly one fifteenth of the image height. Default: None.

• clip_limit (Annotated[float, TuneSpec(low=0.005, high=0.05, step=None, log=True, categories=None, tunable=True)]) – Maximum local contrast amplification factor. Typical range: 0.005–0.05. Lower values suppress noise amplification; higher values make faint colonies stand out more at the cost of amplifying local noise. Default: 0.01.

Returns:

Input image with detect_mat contrast-enhanced. rgb and gray are unchanged.

Return type:

Image

Raises:

ValueError – If the detect_mat value range is invalid for equalization.

References

[1] S. M. Pizer et al., “Adaptive histogram equalization and its variations,” Computer Vision, Graphics, and Image Processing, vol. 39, no. 3, pp. 355–368, Sep. 1987.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of EnhanceLocalContrast before detection. How To: Enhance Low-Contrast Images for a comparison of contrast enhancement methods on real plate images.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

clip_limit: Annotated[float, TuneSpec(0.005, 0.05, log=True)]

kernel_size: Annotated[int | None, TuneSpec(tunable=False)]

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'clip_limit': FieldInfo(annotation=float, required=False, default=0.01, description='Maximum local contrast amplification factor. Typical range: 0.005--0.05. Lower values suppress noise amplification; higher values make faint colonies stand out more at the cost of amplifying local noise. Default: 0.01.', metadata=[TuneSpec(low=0.005, high=0.05, step=None, log=True, categories=None, tunable=True)]), 'kernel_size': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Tile size for local equalization in pixels. Smaller tiles reveal tiny colonies and local features but amplify agar texture; larger tiles produce smoother results. ``None`` auto-selects a tile size of roughly one fifteenth of the image height. Default: ``None``.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

class phenotypic.enhance.FlattenIllumination(*, sigma: Annotated[float, Gt(gt=0.0), TuneSpec(low=40.0, high=300.0, step=None, log=True, categories=None, tunable=True)] = 200.0, gamma_low: Annotated[float, TuneSpec(low=0.3, high=0.8, step=None, log=False, categories=None, tunable=True)] = 0.5, gamma_high: Annotated[float, TuneSpec(low=1.0, high=2.5, step=None, log=False, categories=None, tunable=True)] = 1.5, eps: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 1e-06)

Bases: BackgroundSubtraction

Correct uneven illumination in detect_mat using homomorphic frequency-domain filtering.

Separates the illumination (low-frequency) and reflectance (high-frequency) components in the log domain, applies differential gains to suppress brightness gradients while boosting colony detail, then exponentiates back to the linear domain. The result is clipped to [0.0, 1.0]. Particularly effective for plates with vignetting, scanner lighting bands, or shadow gradients where spatial-domain subtraction is insufficient.

For how enhancement fits into the pipeline, see What Enhancement Actually Does.

Best For:

• Plates with visible vignetting or radial brightness falloff from DSLR or flatbed scanner optics.

• Scanner images with horizontal or vertical lighting bands across the plate surface.

• Plates where uneven agar thickness causes variable background brightness.

• Pre-conditioning before global thresholding on unevenly lit plates.

Consider Also:

• SubtractGaussian for a simpler spatial-domain background subtraction when the illumination gradient is smooth and mild.

• EnhanceLocalContrast when the problem is local contrast variation rather than a large-scale illumination gradient.

• SubtractRollingBall for morphological background estimation when the gradient is driven by colony proximity to the plate edge.

Parameters:

• sigma (Annotated[float, Gt(gt=0.0), TuneSpec(low=40.0, high=300.0, step=None, log=True, categories=None, tunable=True)]) – Gaussian sigma controlling the spatial scale of the estimated illumination field in pixels. Must be large enough to span entire colonies so the low-pass captures only the gradient, not colony signal. A reasonable starting point is several times the diameter of the largest colony. Typical range: 40–300 (resolution-dependent). Default: 200.0.

• gamma_low (Annotated[float, TuneSpec(low=0.3, high=0.8, step=None, log=False, categories=None, tunable=True)]) – Gain applied to the illumination (low-frequency) component. Values below 1.0 suppress illumination variation; 1.0 leaves it unchanged. Typical range: 0.3–0.8. Default: 0.5.

• gamma_high (Annotated[float, TuneSpec(low=1.0, high=2.5, step=None, log=False, categories=None, tunable=True)]) – Gain applied to the reflectance (high-frequency) component. Values above 1.0 enhance colony contrast and surface detail; 1.0 leaves it unchanged. Typical range: 1.0–2.5. Default: 1.5.

• eps (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Small additive constant before the logarithm to prevent log(0) on zero-valued pixels. Typical range: 1e-8–1e-4. Rarely needs adjustment for standard [0, 1] normalised images. Default: 1e-6.

Returns:

Input image with detect_mat illumination-corrected and clipped to [0.0, 1.0]. rgb and gray are unchanged.

Return type:

Image

Raises:

ValueError – If sigma is not positive.

See also

How To: Enhance Low-Contrast Images for a comparison of contrast and illumination correction methods on real plate images. What Enhancement Actually Does for how homomorphic filtering separates illumination from reflectance.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

eps: Annotated[float, TuneSpec(tunable=False)]

gamma_high: Annotated[float, TuneSpec(1.0, 2.5)]

gamma_low: Annotated[float, TuneSpec(0.3, 0.8)]

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'eps': FieldInfo(annotation=float, required=False, default=1e-06, description='Small additive constant before the logarithm to prevent log(0) on zero-valued pixels. Typical range: 1e-8--1e-4. Rarely needs adjustment for standard [0, 1] normalised images. Default: 1e-6.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'gamma_high': FieldInfo(annotation=float, required=False, default=1.5, description='Gain applied to the reflectance (high-frequency) component. Values above 1.0 enhance colony contrast and surface detail; 1.0 leaves it unchanged. Typical range: 1.0--2.5. Default: 1.5.', metadata=[TuneSpec(low=1.0, high=2.5, step=None, log=False, categories=None, tunable=True)]), 'gamma_low': FieldInfo(annotation=float, required=False, default=0.5, description='Gain applied to the illumination (low-frequency) component. Values below 1.0 suppress illumination variation; 1.0 leaves it unchanged. Typical range: 0.3--0.8. Default: 0.5.', metadata=[TuneSpec(low=0.3, high=0.8, step=None, log=False, categories=None, tunable=True)]), 'sigma': FieldInfo(annotation=float, required=False, default=200.0, description='Gaussian sigma controlling the spatial scale of the estimated illumination field in pixels. Must be large enough to span entire colonies so the low-pass captures only the gradient, not colony signal. A reasonable starting point is several times the diameter of the largest colony. Typical range: 40--300 (resolution-dependent).', metadata=[Gt(gt=0.0), TuneSpec(low=40.0, high=300.0, step=None, log=True, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

sigma: Annotated[float, TuneSpec(40.0, 300.0, log=True)]

class phenotypic.enhance.FocusBlobLoG(*, min_radius: Annotated[float, TuneSpec(low=1.0, high=5.0, step=None, log=False, categories=None, tunable=True)] = 3.0, max_radius: Annotated[float, TuneSpec(low=8.0, high=50.0, step=None, log=False, categories=None, tunable=True)] = 12.0, num_scales: Annotated[int, TuneSpec(low=4, high=20, step=None, log=False, categories=None, tunable=True)] = 12)

Bases: FocusBlob

Enhance blob-like colonies in detect_mat with scale-normalised Laplacian of Gaussian.

Applies LoG filtering across a geometric series of Gaussian sigmas and returns the pixel-wise maximum response across all scales. Bright blob-like structures (colonies, inocula, droplets) produce strong peaks regardless of size, making this a robust preprocessing step before thresholding or GMM-based segmentation. The output detect_mat is a response map, not a corrected grayscale image.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Mixed-size colonies on mature plates where small emerging and large mature colonies must both be detected in a single pass.

• Sparse inoculation spots that are faint and nearly invisible against the agar background.

• Low-contrast or shadowed regions where the LoG emphasizes blob structure over absolute intensity.

• Preprocessing before thresholding to sharpen blob boundaries and suppress gradual illumination variation.

Consider Also:

• FocusEdgeSato for elongated or filamentous colony structures where the LoG’s isotropic assumption is a poor fit.

• FocusEdgeLaplace for simpler single-scale edge detection when colony sizes are uniform.

• SubtractGaussian when the primary issue is a broad illumination gradient rather than blob emphasis.

Parameters:

• min_radius (Annotated[float, TuneSpec(low=1.0, high=5.0, step=None, log=False, categories=None, tunable=True)]) – Smallest target blob radius in pixels. Blobs smaller than this produce weaker LoG responses. Typical range: 1.0–15.0 at standard resolutions; scale proportionally for higher-resolution scans. Default: 3.0.

• max_radius (Annotated[float, TuneSpec(low=8.0, high=50.0, step=None, log=False, categories=None, tunable=True)]) – Largest target blob radius in pixels. Blobs larger than this also produce weaker responses. Typical range: 8.0–60.0 at standard resolutions. Default: 12.0.

• num_scales (Annotated[int, TuneSpec(low=4, high=20, step=None, log=False, categories=None, tunable=True)]) – Number of logarithmically spaced sigma values between min_radius / sqrt(2) and max_radius / sqrt(2). More scales improve size discrimination across the radius range at higher compute cost. Typical range: 4–20. Default: 12.

Returns:

Input image with detect_mat replaced by the scale-normalised LoG response map. rgb and gray are unchanged.

Return type:

Image

Raises:

ValueError – If min_radius <= 0, min_radius >= max_radius, or num_scales < 1.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of blob enhancement on plate images. What Enhancement Actually Does for background on scale-space blob detection and LoG theory.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

max_radius: Annotated[float, TuneSpec(8.0, 50.0)]

min_radius: Annotated[float, TuneSpec(1.0, 5.0)]

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'max_radius': FieldInfo(annotation=float, required=False, default=12.0, description='Largest target blob radius in pixels. Blobs larger than this also produce weaker responses. Typical range: 8.0--60.0 at standard resolutions. Default: 12.0.', metadata=[TuneSpec(low=8.0, high=50.0, step=None, log=False, categories=None, tunable=True)]), 'min_radius': FieldInfo(annotation=float, required=False, default=3.0, description='Smallest target blob radius in pixels. Blobs smaller than this produce weaker LoG responses. Typical range: 1.0--15.0 at standard resolutions; scale proportionally for higher-resolution scans. Default: 3.0.', metadata=[TuneSpec(low=1.0, high=5.0, step=None, log=False, categories=None, tunable=True)]), 'num_scales': FieldInfo(annotation=int, required=False, default=12, description='Number of logarithmically spaced sigma values between ``min_radius / sqrt(2)`` and ``max_radius / sqrt(2)``. More scales improve size discrimination across the radius range at higher compute cost. Typical range: 4--20. Default: 12.', metadata=[TuneSpec(low=4, high=20, step=None, log=False, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

num_scales: Annotated[int, TuneSpec(4, 20)]

class phenotypic.enhance.FocusEdgeFrangi(*, sigmas: tuple[float, ...] = (0.5, 1, 1.5), alpha: float = 0.5, beta: Annotated[float, TuneSpec(low=0.1, high=1.0, step=None, log=False, categories=None, tunable=True)] = 0.5, gamma: float | None = None, black_ridges: bool = False)

Bases: FocusEdge

Enhance elongated structures in detect_mat using multi-scale Frangi vesselness filtering.

Computes Hessian matrix eigenvalues at each sigma scale and combines them into a vesselness score that responds strongly to ridge-like features — hyphae, mycelial branches, biofilm edges — while suppressing blob-like colonies and flat agar background. The output is a [0, 1] probability-like map that typically feeds into FilamentousFungiDetector or a hysteresis threshold. For algorithm details see The Filamentous Fungi Detection Algorithm.

Best For:

• Filamentous fungi (Neurospora, Aspergillus) with branching hyphae resolved to 2–8 px wide at the imaging scale.

• Mycelial networks and biofilm ridge structures that global intensity thresholding misses.

• Pre-filtering before FilamentousFungiDetector to produce a clean hyphal evidence map.

• Plates where hyphae span a range of widths and a multi-sigma sweep is needed to cover all branch generations.

Consider Also:

• FocusEdgeMeijering for very fine, isolated filaments where the analytic alpha optimum and simpler parameterisation are preferred.

• FocusEdgeSato when continuous tubular structures with different eigenvalue-ratio behaviour are the target.

• FocusEdgePhase for contrast-invariant edge enhancement on plates with uneven illumination.

• StructureSmoothing for anisotropic pre-smoothing along hyphal orientation before ridge detection.

Parameters:

• sigmas (tuple[float, ...]) – Gaussian standard deviations (pixels) at which the Hessian is evaluated. Each sigma responds most strongly to ridges whose cross-sectional half-width is approximately that value. Include sigmas spanning the full range of expected hyphal widths; the per-pixel maximum across all scales is taken, so additional sigmas can only raise the response. A reasonable starting point for agar plate scans at 600 dpi, where hyphae typically appear 2–8 px wide, is (0.5, 1, 1.5) to (1, 2, 3, 4); extend the upper bound for mature thick mycelium or coarser imaging resolution. Default: (0.5, 1, 1.5).

• alpha (float) – Plate-likeness sensitivity in the vesselness formula. Controls how strongly the filter penalises structures that deviate from a purely elongated ridge. In 2-D images this parameter has no numerical effect because the plate-sensitivity ratio is undefined and omitted from the 2-D vesselness formula; it is included only for compatibility with 3-D use. Typical range: 0.1–1.0. Default: 0.5.

• beta (Annotated[float, TuneSpec(low=0.1, high=1.0, step=None, log=False, categories=None, tunable=True)]) – Blob-likeness sensitivity. Lower values make the filter more permissive of rounded or imperfect ridges (useful at branching junctions and thick hyphal segments); higher values restrict responses to more purely elongated structures. Typical range: 0.1–1.0. Default: 0.5.

• gamma (float | None) – Background suppression threshold based on the Hessian Frobenius norm. None (default) uses half the maximum Hessian norm per scale, adapting to the actual contrast in each image. An explicit positive value provides a fixed threshold useful when comparing results across images with different illumination. Default: None.

• black_ridges (bool) – Polarity of the target ridges. False (default) detects bright ridges on a dark background, matching the detect_mat convention where hyphae appear bright. True detects dark ridges on a bright background (e.g. transmitted-light microscopy). Default: False.

Returns:

Input image with detect_mat replaced by the [0, 1] vesselness response map. rgb and gray are unchanged.

Return type:

Image

References

[1] A. F. Frangi, W. J. Niessen, K. L. Vincken, and M. A. Viergever, “Multiscale vessel enhancement filtering,” in Proc. MICCAI, 1998, pp. 130–137.

See also

Tutorial 10: Detecting Filamentous Fungi for a visual walkthrough of filamentous fungi detection. The Filamentous Fungi Detection Algorithm for the theory behind Hessian-based vesselness filtering.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

alpha: float

beta: Annotated[float, TuneSpec(0.1, 1.0)]

black_ridges: bool

gamma: float | None

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'alpha': FieldInfo(annotation=float, required=False, default=0.5, description='Plate-likeness sensitivity in the vesselness formula. Controls how strongly the filter penalises structures that deviate from a purely elongated ridge. In 2-D images this parameter has no numerical effect because the plate-sensitivity ratio is undefined and omitted from the 2-D vesselness formula; it is included only for compatibility with 3-D use. Typical range: 0.1--1.0.'), 'beta': FieldInfo(annotation=float, required=False, default=0.5, description='Blob-likeness sensitivity. Lower values make the filter more permissive of rounded or imperfect ridges (useful at branching junctions and thick hyphal segments); higher values restrict responses to more purely elongated structures. Typical range: 0.1--1.0. Default: 0.5.', metadata=[TuneSpec(low=0.1, high=1.0, step=None, log=False, categories=None, tunable=True)]), 'black_ridges': FieldInfo(annotation=bool, required=False, default=False, description='Polarity of the target ridges. ``False`` (default) detects bright ridges on a dark background, matching the ``detect_mat`` convention where hyphae appear bright. ``True`` detects dark ridges on a bright background (e.g. transmitted-light microscopy). Default: ``False``.'), 'gamma': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Background suppression threshold based on the Hessian Frobenius norm. ``None`` (default) uses half the maximum Hessian norm per scale, adapting to the actual contrast in each image. An explicit positive value provides a fixed threshold useful when comparing results across images with different illumination.'), 'sigmas': FieldInfo(annotation=tuple[float, ...], required=False, default=(0.5, 1, 1.5), description='Gaussian standard deviations (pixels) at which the Hessian is evaluated. Each sigma responds most strongly to ridges whose cross-sectional half-width is approximately that value. Include sigmas spanning the full range of expected hyphal widths; the per-pixel maximum across all scales is taken, so additional sigmas can only raise the response. A reasonable starting point for agar plate scans at 600 dpi, where hyphae typically appear 2--8 px wide, is ``(0.5, 1, 1.5)`` to ``(1, 2, 3, 4)``; extend the upper bound for mature thick mycelium or coarser imaging resolution.')}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

sigmas: tuple[float, ...]

class phenotypic.enhance.FocusEdgeHessian(*, sigmas: tuple[float, ...] = (1, 2, 3), alpha: float = 0.5, beta: Annotated[float, TuneSpec(low=0.1, high=1.0, step=None, log=False, categories=None, tunable=True)] = 0.5, gamma: Annotated[float, TuneSpec(low=5.0, high=25.0, step=None, log=True, categories=None, tunable=True)] = 15, black_ridges: bool = False, mode: str = 'reflect', cval: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0)

Bases: FocusEdge

Enhance colony boundaries and ridge-like structures via multi-scale Hessian filtering.

Computes Hessian matrix eigenvalues at each sigma scale and combines them into a hybrid vesselness score that highlights regions with high curvature — colony edges, filament ridges, biofilm features — while suppressing flat agar background. Unlike the Frangi filter, background pixels (with response ≤ 0) are set to 1, so the output map inverts the agar-to-colony contrast and is best interpreted as a ridge-strength mask. For algorithm details see What Enhancement Actually Does.

Best For:

• Sharp colony-agar boundaries on plates with compact bacterial or yeast colonies resolved at 1–5 px edge width.

• Size-heterogeneous plates where a tuple of sigmas spanning the full colony size range provides scale-invariant edge response.

• Thin filaments and branching structures with low intensity contrast that global thresholding misses.

• Textured colonies or biofilms where internal ridge structure aids downstream morphology analysis.

Consider Also:

• FocusEdgeFrangi for strictly elongated hyphae and mycelial networks where background suppression via the adaptive gamma rule is preferred.

• FocusEdgeMeijering for very fine neurite-like filaments where the analytic shape-parameter optimum is preferred.

• FocusEdgeLaplace for simpler single-scale second-derivative edge detection without multi-scale parameter tuning.

Parameters:

• sigmas (tuple[float, ...]) – Gaussian standard deviations (pixels) at which the Hessian is evaluated. Each value responds most strongly to ridges and edges whose cross-sectional half-width is approximately that number of pixels; the per-pixel maximum across all scales is taken. Typical range: (1, 2, 3) for standard plate scans; extend to (1, 5) or wider when colony sizes vary broadly. A reasonable starting point for whole-plate scans at 600 dpi is (1, 2, 3); add larger sigmas for mature large colonies or thick filaments. Default: (1, 2, 3).

• alpha (float) – Plate-likeness sensitivity in the vesselness formula. In 2-D images this parameter has no numerical effect because the plate-sensitivity ratio is undefined and omitted from the 2-D formula; it is included only for compatibility with 3-D use. Typical range: 0.1–1.0. Default: 0.5.

• beta (Annotated[float, TuneSpec(low=0.1, high=1.0, step=None, log=False, categories=None, tunable=True)]) – Blob-likeness sensitivity. Lower values make the filter more permissive of rounded, curved, or imperfect ridges (useful for circular colony edges); higher values restrict responses to more elongated, line-like structures. Typical range: 0.1–1.0. Default: 0.5.

• gamma (Annotated[float, TuneSpec(low=5.0, high=25.0, step=None, log=True, categories=None, tunable=True)]) – Fixed background suppression threshold applied to the Hessian Frobenius norm. Only regions with norm above this level produce nonzero responses; regions below it are set to 1 (background convention of the hybrid Hessian filter). Typical range: 10–20. Lower values (5–10) recover faint colony edges; higher values (20–25) sharpen the contrast between ridges and flat agar. Default: 15.

• black_ridges (bool) – Polarity of the target ridges. False (default) detects bright ridges on a dark background, matching the detect_mat convention where colonies and hyphae appear bright. True detects dark ridges on a bright background. Default: False.

• mode (str) – Boundary padding mode for Gaussian derivative computation. Accepted values: 'reflect', 'constant', 'nearest', 'mirror', 'wrap'. Default: 'reflect'.

• cval (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Fill value used when mode='constant'. Has no effect for any other mode. Default: 0.

Returns:

Input image with detect_mat replaced by the Hessian ridge response map. rgb and gray are unchanged.

Return type:

Image

References

[1] A. F. Frangi, W. J. Niessen, K. L. Vincken, and M. A. Viergever, “Multiscale vessel enhancement filtering,” in Proc. MICCAI, 1998, pp. 130–137.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of ridge and edge enhancement on plate images. What Enhancement Actually Does for background on Hessian-based structure detection.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

alpha: float

beta: Annotated[float, TuneSpec(0.1, 1.0)]

black_ridges: bool

cval: Annotated[float, TuneSpec(tunable=False)]

gamma: Annotated[float, TuneSpec(5.0, 25.0, log=True)]

mode: str

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'alpha': FieldInfo(annotation=float, required=False, default=0.5, description='Plate-likeness sensitivity in the vesselness formula. In 2-D images this parameter has no numerical effect because the plate-sensitivity ratio is undefined and omitted from the 2-D formula; it is included only for compatibility with 3-D use. Typical range: 0.1--1.0. Default: 0.5.'), 'beta': FieldInfo(annotation=float, required=False, default=0.5, description='Blob-likeness sensitivity. Lower values make the filter more permissive of rounded, curved, or imperfect ridges (useful for circular colony edges); higher values restrict responses to more elongated, line-like structures. Typical range: 0.1--1.0.', metadata=[TuneSpec(low=0.1, high=1.0, step=None, log=False, categories=None, tunable=True)]), 'black_ridges': FieldInfo(annotation=bool, required=False, default=False, description='Polarity of the target ridges. ``False`` (default) detects bright ridges on a dark background, matching the ``detect_mat`` convention where colonies and hyphae appear bright. ``True`` detects dark ridges on a bright background. Default: ``False``.'), 'cval': FieldInfo(annotation=float, required=False, default=0, description="Fill value used when ``mode='constant'``. Has no effect for any other mode. Default: 0.", metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'gamma': FieldInfo(annotation=float, required=False, default=15, description='Fixed background suppression threshold applied to the Hessian Frobenius norm. Only regions with norm above this level produce nonzero responses; regions below it are set to 1 (background convention of the hybrid Hessian filter). Typical range: 10--20. Lower values (5--10) recover faint colony edges; higher values (20--25) sharpen the contrast between ridges and flat agar.', metadata=[TuneSpec(low=5.0, high=25.0, step=None, log=True, categories=None, tunable=True)]), 'mode': FieldInfo(annotation=str, required=False, default='reflect', description="Boundary padding mode for Gaussian derivative computation. Accepted values: ``'reflect'``, ``'constant'``, ``'nearest'``, ``'mirror'``, ``'wrap'``. Default: ``'reflect'``."), 'sigmas': FieldInfo(annotation=tuple[float, ...], required=False, default=(1, 2, 3), description='Gaussian standard deviations (pixels) at which the Hessian is evaluated. Each value responds most strongly to ridges and edges whose cross-sectional half-width is approximately that number of pixels; the per-pixel maximum across all scales is taken. Typical range: ``(1, 2, 3)`` for standard plate scans; extend to ``(1, 5)`` or wider when colony sizes vary broadly. A reasonable starting point for whole-plate scans at 600 dpi is ``(1, 2, 3)``; add larger sigmas for mature large colonies or thick filaments. Default: ``(1, 2, 3)``.')}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

sigmas: tuple[float, ...]

class phenotypic.enhance.FocusEdgeLaplace(*, kernel_size: Annotated[int | None, TuneSpec(low=3, high=7, step=2, log=False, categories=None, tunable=True)] = 3, mask: WithJsonSchema(json_schema={'type': 'array', 'items': {}}, mode=None)] | None = None)

Bases: FocusEdge

Enhance colony edges in detect_mat with a discrete Laplacian operator.

Applies a discrete second-derivative Laplacian that responds strongly to rapid intensity changes, highlighting colony margins and ring-like features such as swarming fronts. The output is an edge-response map suitable as a preprocessing step for contour detection, watershed seeding, or separating touching colonies.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Emphasizing colony edges before edge-based or contour-based segmentation.

• Detecting ring patterns around swarming colonies for motility phenotyping.

• Generating boundary seeds for watershed segmentation when colonies are touching.

Consider Also:

• FocusEdgeHessian for multi-scale ridge and edge detection with additional control over scale and background suppression.

• SharpenEdgeGauss for edge enhancement that retains the original intensity profile rather than producing a pure edge map.

• FocusEdgePhase for contrast-invariant edge detection under uneven illumination.

Parameters:

• kernel_size (Annotated[int | None, TuneSpec(low=3, high=7, step=2, log=False, categories=None, tunable=True)]) – Size of the Laplacian convolution kernel in pixels. Smaller values (3) capture fine colony edges but amplify noise; larger values (5–7) smooth noise and emphasize broader colony boundaries. Default: 3.

• mask (Annotated[ndarray, BeforeValidator(func=~phenotypic.sdk_.typing_._coerce_to_ndarray, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~phenotypic.sdk_.typing_._ndarray_to_list, return_type=list, when_used=always), WithJsonSchema(json_schema={'type': 'array', 'items': {}}, mode=None)] | None) – Boolean or 0/1 array restricting processing to a region of interest (e.g., the circular plate area). None processes the full image. Default: None.

Returns:

Input image with detect_mat replaced by the Laplacian edge response. rgb and gray are unchanged.

Return type:

Image

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of edge enhancement on plate images. What Enhancement Actually Does for how edge-response maps fit into the pipeline model.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

kernel_size: Annotated[int | None, TuneSpec(3, 7, step=2)]

mask: NdArrayField | None

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'kernel_size': FieldInfo(annotation=Union[int, NoneType], required=False, default=3, description='Size of the Laplacian convolution kernel in pixels. Smaller values (3) capture fine colony edges but amplify noise; larger values (5--7) smooth noise and emphasize broader colony boundaries. Default: 3.', metadata=[TuneSpec(low=3, high=7, step=2, log=False, categories=None, tunable=True)]), 'mask': FieldInfo(annotation=Union[Annotated[ndarray, BeforeValidator, PlainSerializer, WithJsonSchema], NoneType], required=False, default=None, description='Boolean or 0/1 array restricting processing to a region of interest (e.g., the circular plate area). ``None`` processes the full image. Default: ``None``.')}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

class phenotypic.enhance.FocusEdgeMeijering(*, sigmas: tuple[float, ...] = (1, 2, 3), alpha: float | None = None, black_ridges: bool = False, mode: str = 'reflect', cval: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0)

Bases: FocusEdge

Enhance fine filamentous ridges in detect_mat using the Meijering neuriteness filter.

Computes the Meijering neuriteness measure from Hessian eigenvalues at each sigma scale, using an analytically derived shape parameter that maximally suppresses blob-like and isotropic responses while favouring elongated, thread-like features. The output is a [0, 1] ridge-strength map suited to detecting delicate hyphae, actinomycete filaments, and fine biofilm ridge networks. For algorithm details see What Enhancement Actually Does.

Best For:

• Delicate fungal hyphae and actinomycete filaments resolved to 2–5 px width where the analytic shape optimum provides maximum elongation selectivity.

• Sparse mycelial networks with well-separated filaments where sensitivity to thin ridges is more important than junction detection.

• Fine biofilm grooves or wrinkle networks in bacterial colony morphology plates.

• Pipelines where minimising the number of parameters to tune is a priority (alpha defaults to the analytic optimum).

Consider Also:

• FocusEdgeFrangi for broader mycelial networks with independent control over plate-like and blob-like sensitivity.

• FocusEdgeSato for thicker, continuous tubular structures with a different eigenvalue-combination strategy.

• FocusEdgeHessian when combined edge and colony boundary detection alongside filament ridges is needed.

• StructureSmoothing for anisotropic pre-smoothing along hyphal orientation before this ridge filter.

Parameters:

• sigmas (tuple[float, ...]) – Gaussian standard deviations (pixels) at which the Hessian is evaluated. Each value responds most strongly to ridges whose cross-sectional half-width is approximately that number of pixels; the per-pixel maximum across all scales is taken. Typical range: (1, 2, 3) for standard plate scans; extend the lower bound to 0.5 for very thin filaments at high magnification or the upper bound to 5–8 for thick mycelial mats. Default: (1, 2, 3).

• alpha (float | None) – Shape parameter controlling how the Hessian eigenvalues are combined into a neuriteness score. None (default) uses the analytically derived optimum -1/(ndim+1) (-1/3 for 2-D images), which maximally suppresses blob-like structures while retaining elongated ridges. Manual values closer to 0 reduce blob suppression; more-negative values sharpen the ridge/blob discrimination. Default: None.

• black_ridges (bool) – Polarity of the target ridges. False (default) detects bright ridges on a dark background, matching the detect_mat convention where hyphae appear bright. True detects dark ridges on a bright background. Default: False.

• mode (str) – Boundary padding mode for Gaussian derivative computation. Accepted values: 'constant', 'reflect', 'wrap', 'nearest', 'mirror'. Default: 'reflect'.

• cval (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Fill value used when mode='constant'. Has no effect for any other mode. Default: 0.

Returns:

Input image with detect_mat replaced by the Meijering neuriteness response map. rgb and gray are unchanged.

Return type:

Image

References

[1] E. Meijering, M. Jacob, J.-C. F. Sarria, P. Steiner, H. Hirling, and M. Unser, “Design and validation of a tool for neurite tracing and analysis in fluorescence microscopy images,” Cytometry Part A, vol. 58, no. 2, pp. 167–176, Apr. 2004.

See also

Tutorial 10: Detecting Filamentous Fungi for a visual walkthrough of filamentous fungi detection using ridge filters. Tutorial 3: Enhancing Before Detection for a broader enhancement pipeline walkthrough on plate images. What Enhancement Actually Does for background on Hessian-based ridge detection methods.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

alpha: float | None

black_ridges: bool

cval: Annotated[float, TuneSpec(tunable=False)]

mode: str

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'alpha': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Shape parameter controlling how the Hessian eigenvalues are combined into a neuriteness score. ``None`` (default) uses the analytically derived optimum ``-1/(ndim+1)`` (``-1/3`` for 2-D images), which maximally suppresses blob-like structures while retaining elongated ridges. Manual values closer to 0 reduce blob suppression; more-negative values sharpen the ridge/blob discrimination. Default: ``None``.'), 'black_ridges': FieldInfo(annotation=bool, required=False, default=False, description='Polarity of the target ridges. ``False`` (default) detects bright ridges on a dark background, matching the ``detect_mat`` convention where hyphae appear bright. ``True`` detects dark ridges on a bright background. Default: ``False``.'), 'cval': FieldInfo(annotation=float, required=False, default=0, description="Fill value used when ``mode='constant'``. Has no effect for any other mode. Default: 0.", metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'mode': FieldInfo(annotation=str, required=False, default='reflect', description="Boundary padding mode for Gaussian derivative computation. Accepted values: ``'constant'``, ``'reflect'``, ``'wrap'``, ``'nearest'``, ``'mirror'``. Default: ``'reflect'``."), 'sigmas': FieldInfo(annotation=tuple[float, ...], required=False, default=(1, 2, 3), description='Gaussian standard deviations (pixels) at which the Hessian is evaluated. Each value responds most strongly to ridges whose cross-sectional half-width is approximately that number of pixels; the per-pixel maximum across all scales is taken. Typical range: ``(1, 2, 3)`` for standard plate scans; extend the lower bound to 0.5 for very thin filaments at high magnification or the upper bound to 5--8 for thick mycelial mats. Default: ``(1, 2, 3)``.')}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

sigmas: tuple[float, ...]

class phenotypic.enhance.FocusEdgePhase(*, n_scale: Annotated[int, Ge(ge=1), TuneSpec(low=3, high=6, step=None, log=False, categories=None, tunable=True)] = 4, n_orient: Annotated[int, Ge(ge=1), TuneSpec(low=4, high=8, step=None, log=False, categories=None, tunable=True)] = 6, min_wavelength: Annotated[float, Ge(ge=2.0), TuneSpec(low=2.0, high=10.0, step=None, log=False, categories=None, tunable=True)] = 3.0, mult: Annotated[float, Gt(gt=1.0), TuneSpec(low=1.5, high=3.0, step=None, log=False, categories=None, tunable=True)] = 2.1, sigma_onf: Annotated[float, Ge(ge=0.1), Le(le=1.0), TuneSpec(low=0.1, high=1.0, step=None, log=False, categories=None, tunable=True)] = 0.55, k: Annotated[float, Ge(ge=0.0), TuneSpec(low=0.5, high=20.0, step=None, log=False, categories=None, tunable=True)] = 2.0, cutoff: Annotated[float, Gt(gt=0.0), Lt(lt=1.0), TuneSpec(low=0.3, high=0.7, step=None, log=False, categories=None, tunable=True)] = 0.5, g: Annotated[float, Gt(gt=0.0), TuneSpec(low=2.0, high=20.0, step=None, log=False, categories=None, tunable=True)] = 10.0, noise_method: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = -1.0, output: Literal['M', 'm', 'pc_sum'] = 'pc_sum')

Bases: FocusEdge

Enhance colony edges in detect_mat using contrast-invariant phase congruency.

Detects features where log-Gabor Fourier components are maximally in phase, producing an edge response that depends on phase agreement rather than amplitude. The result is invariant to local illumination level and scanner vignetting, making faint or translucent colony boundaries visible even where intensity-gradient methods fail. For algorithm details see What Enhancement Actually Does.

Best For:

• Colony boundaries that vary in opacity or contrast across the plate due to pigmentation differences, agar depth variation, or colony age.

• Plates with scanner vignetting or uneven illumination where gradient-based filters produce inconsistent edge strength.

• Faint, translucent colonies on bright agar where the amplitude signal is weak but phase coherence is preserved.

• Filamentous fungi plates where edges span a wide range of orientations and n_orient=8 captures all hyphal angles.

Consider Also:

• FocusEdgeFrangi for elongated hyphae when vesselness selectivity for ridge shape is more important than illumination invariance.

• FocusEdgeHessian for multi-scale ridge and edge detection with explicit blob-sensitivity control.

• SharpenEdgeGauss for edge sharpening that preserves the original intensity profile on uniformly illuminated plates.

Parameters:

• n_scale (Annotated[int, Ge(ge=1), TuneSpec(low=3, high=6, step=None, log=False, categories=None, tunable=True)]) – Number of log-Gabor octave scales. More scales integrate phase evidence over a wider spatial frequency range, giving a smoother but spatially broader response. Typical range: 3–6. Default: 4.

• n_orient (Annotated[int, Ge(ge=1), TuneSpec(low=4, high=8, step=None, log=False, categories=None, tunable=True)]) – Number of oriented filter lobes. 6 gives 30-degree angular spacing (suitable for circular yeast colony edges); 8 gives 22.5-degree spacing and better sensitivity to hyphae at arbitrary angles. Typical range: 4–8. Default: 6.

• min_wavelength (Annotated[float, Ge(ge=2.0), TuneSpec(low=2.0, high=10.0, step=None, log=False, categories=None, tunable=True)]) – Center wavelength (pixels) of the finest log-Gabor scale. Should be matched to the narrowest expected colony edge width; must be >= 2 (Nyquist limit enforced by validator). Smaller values detect finer high-frequency features; larger values focus on broader edges. Default: 3.0.

• mult (Annotated[float, Gt(gt=1.0), TuneSpec(low=1.5, high=3.0, step=None, log=False, categories=None, tunable=True)]) – Ratio between successive scale wavelengths. Together with sigma_onf it determines inter-scale spectral coverage. 2.1 is the upstream default. For even coverage of the spectrum Kovesi recommends pairing mult and sigma_onf together; e.g. sigma_onf=0.55 / mult=3 gives roughly 2-octave bandwidth and sigma_onf=0.75 / mult=1.6 gives roughly 1-octave bandwidth. Re-tune both whenever either changes. Must be > 1. Default: 2.1.

• sigma_onf (Annotated[float, Ge(ge=0.1), Le(le=1.0), TuneSpec(low=0.1, high=1.0, step=None, log=False, categories=None, tunable=True)]) – Log-Gabor bandwidth ratio (standard deviation of the Gaussian transfer function divided by the filter center frequency). Smaller values give wider bandwidth (more octaves per scale, broadband, suited for plates with a wide range of colony sizes); larger values give narrower, more frequency-selective bandwidth. For even spectral coverage pair with mult per the upstream table (0.55 with mult=3, 0.75 with mult=1.6). Valid range: 0.1–1.0. Default: 0.55.

• k (Annotated[float, Ge(ge=0.0), TuneSpec(low=0.5, high=20.0, step=None, log=False, categories=None, tunable=True)]) – Noise threshold multiplier in units of the estimated Rayleigh noise standard deviation. Higher values (5–20) suppress more noise at the cost of missing faint colony edges; lower values (1–3) maximise edge recall on clean images. Value 0 disables noise thresholding entirely. Default: 2.0.

• cutoff (Annotated[float, Gt(gt=0.0), Lt(lt=1.0), TuneSpec(low=0.3, high=0.7, step=None, log=False, categories=None, tunable=True)]) – Frequency spread penalty threshold. Phase congruency values are penalised via a sigmoid when the multi-scale amplitude spread falls below this fraction, discouraging single-scale responses. Valid range: (0, 1) exclusive. Default: 0.5.

• g (Annotated[float, Gt(gt=0.0), TuneSpec(low=2.0, high=20.0, step=None, log=False, categories=None, tunable=True)]) – Sigmoid sharpness controlling the transition from penalised to unpenalised frequency spread. Higher values create a near-binary gate; lower values create a gradual blend. Must be > 0. Default: 10.0.

• noise_method (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Noise threshold estimation strategy. -1.0 (default) estimates from the median of the smallest-scale filter amplitude (robust, recommended for heterogeneous plate populations). -2.0 uses the Rayleigh histogram mode (more robust on images with strong background gradients). Any value >= 0 bypasses estimation and uses that value as a fixed threshold, enabling fully deterministic pipelines. Default: -1.0.

• output (Literal['M', 'm', 'pc_sum']) – Which phase congruency quantity to store in detect_mat. 'pc_sum' (default) is the mean phase congruency across all orientations, normalised to [0, 1]; best general-purpose edge map for downstream thresholding. 'M' is the maximum eigenvalue of the phase congruency covariance tensor (edge strength along continuous curves). 'm' is the minimum eigenvalue (corner and junction strength). Accepted values: 'pc_sum', 'M', 'm'. Default: 'pc_sum'.

Returns:

Input image with detect_mat replaced by the phase congruency map, clipped to [0, 1]. rgb and gray are unchanged.

Return type:

Image

Raises:

ValueError – If n_scale < 1, n_orient < 1, min_wavelength < 2, mult <= 1, sigma_onf outside [0.1, 1.0], k < 0, cutoff outside (0, 1), or g <= 0.

References

[1] P. Morrone and R. A. Owens, “Feature detection from local energy,” Pattern Recognit. Lett., vol. 6, no. 5, pp. 303–313, Dec. 1987.

[2] M. C. Morrone and D. C. Burr, “Feature detection in human vision: A phase-dependent energy model,” Proc. R. Soc. London, Ser. B, vol. 235, no. 1280, pp. 221–245, Dec. 1988.

[3] P. Kovesi, “Phase congruency: A low-level image invariant,” Psychol. Res., vol. 64, no. 2, pp. 136–148, Aug. 2000.

[4] D. J. Field, “Relations between the statistics of natural images and the response properties of cortical cells,” J. Opt. Soc. Am. A, vol. 4, no. 12, pp. 2379–2394, Dec. 1987.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of contrast-invariant enhancement on plate images. What Enhancement Actually Does for background on phase congruency and the Local Energy Model.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

cutoff: Annotated[float, TuneSpec(0.3, 0.7)]

g: Annotated[float, TuneSpec(2.0, 20.0)]

k: Annotated[float, TuneSpec(0.5, 20.0)]

min_wavelength: Annotated[float, TuneSpec(2.0, 10.0)]

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'cutoff': FieldInfo(annotation=float, required=False, default=0.5, description='Frequency spread penalty threshold. Phase congruency values are penalised via a sigmoid when the multi-scale amplitude spread falls below this fraction, discouraging single-scale responses. Valid range: (0, 1) exclusive. Default: 0.5.', metadata=[Gt(gt=0.0), Lt(lt=1.0), TuneSpec(low=0.3, high=0.7, step=None, log=False, categories=None, tunable=True)]), 'g': FieldInfo(annotation=float, required=False, default=10.0, description='Sigmoid sharpness controlling the transition from penalised to unpenalised frequency spread. Higher values create a near-binary gate; lower values create a gradual blend. Must be > 0.', metadata=[Gt(gt=0.0), TuneSpec(low=2.0, high=20.0, step=None, log=False, categories=None, tunable=True)]), 'k': FieldInfo(annotation=float, required=False, default=2.0, description='Noise threshold multiplier in units of the estimated Rayleigh noise standard deviation. Higher values (5--20) suppress more noise at the cost of missing faint colony edges; lower values (1--3) maximise edge recall on clean images. Value 0 disables noise thresholding entirely. Default: 2.0.', metadata=[Ge(ge=0.0), TuneSpec(low=0.5, high=20.0, step=None, log=False, categories=None, tunable=True)]), 'min_wavelength': FieldInfo(annotation=float, required=False, default=3.0, description='Center wavelength (pixels) of the finest log-Gabor scale. Should be matched to the narrowest expected colony edge width; must be >= 2 (Nyquist limit enforced by validator). Smaller values detect finer high-frequency features; larger values focus on broader edges. Default: 3.0.', metadata=[Ge(ge=2.0), TuneSpec(low=2.0, high=10.0, step=None, log=False, categories=None, tunable=True)]), 'mult': FieldInfo(annotation=float, required=False, default=2.1, description='Ratio between successive scale wavelengths. Together with ``sigma_onf`` it determines inter-scale spectral coverage. ``2.1`` is the upstream default. For even coverage of the spectrum Kovesi recommends pairing ``mult`` and ``sigma_onf`` together; e.g. ``sigma_onf=0.55`` / ``mult=3`` gives roughly 2-octave bandwidth and ``sigma_onf=0.75`` / ``mult=1.6`` gives roughly 1-octave bandwidth. Re-tune both whenever either changes. Must be > 1.', metadata=[Gt(gt=1.0), TuneSpec(low=1.5, high=3.0, step=None, log=False, categories=None, tunable=True)]), 'n_orient': FieldInfo(annotation=int, required=False, default=6, description='Number of oriented filter lobes. 6 gives 30-degree angular spacing (suitable for circular yeast colony edges); 8 gives 22.5-degree spacing and better sensitivity to hyphae at arbitrary angles. Typical range: 4--8. Default: 6.', metadata=[Ge(ge=1), TuneSpec(low=4, high=8, step=None, log=False, categories=None, tunable=True)]), 'n_scale': FieldInfo(annotation=int, required=False, default=4, description='Number of log-Gabor octave scales. More scales integrate phase evidence over a wider spatial frequency range, giving a smoother but spatially broader response. Typical range: 3--6.', metadata=[Ge(ge=1), TuneSpec(low=3, high=6, step=None, log=False, categories=None, tunable=True)]), 'noise_method': FieldInfo(annotation=float, required=False, default=-1.0, description='Noise threshold estimation strategy. ``-1.0`` (default) estimates from the median of the smallest-scale filter amplitude (robust, recommended for heterogeneous plate populations). ``-2.0`` uses the Rayleigh histogram mode (more robust on images with strong background gradients). Any value >= 0 bypasses estimation and uses that value as a fixed threshold, enabling fully deterministic pipelines. Default: -1.0.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'output': FieldInfo(annotation=Literal['M', 'm', 'pc_sum'], required=False, default='pc_sum', description="Which phase congruency quantity to store in ``detect_mat``. ``'pc_sum'`` (default) is the mean phase congruency across all orientations, normalised to [0, 1]; best general-purpose edge map for downstream thresholding. ``'M'`` is the maximum eigenvalue of the phase congruency covariance tensor (edge strength along continuous curves). ``'m'`` is the minimum eigenvalue (corner and junction strength). Accepted values: ``'pc_sum'``, ``'M'``, ``'m'``. Default: ``'pc_sum'``."), 'sigma_onf': FieldInfo(annotation=float, required=False, default=0.55, description='Log-Gabor bandwidth ratio (standard deviation of the Gaussian transfer function divided by the filter center frequency). Smaller values give wider bandwidth (more octaves per scale, broadband, suited for plates with a wide range of colony sizes); larger values give narrower, more frequency-selective bandwidth. For even spectral coverage pair with ``mult`` per the upstream table (``0.55`` with ``mult=3``, ``0.75`` with ``mult=1.6``). Valid range: 0.1--1.0. Default: 0.55.', metadata=[Ge(ge=0.1), Le(le=1.0), TuneSpec(low=0.1, high=1.0, step=None, log=False, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

mult: Annotated[float, TuneSpec(1.5, 3.0)]

n_orient: Annotated[int, TuneSpec(4, 8)]

n_scale: Annotated[int, TuneSpec(3, 6)]

noise_method: Annotated[float, TuneSpec(tunable=False)]

output: Literal['M', 'm', 'pc_sum']

sigma_onf: Annotated[float, TuneSpec(0.1, 1.0)]

class phenotypic.enhance.FocusEdgeSato(*, sigmas: tuple[float, ...] = (1, 2, 3), black_ridges: bool = False, mode: str = 'reflect', cval: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0)

Bases: FocusEdge

Enhance hyphal ridges and tubular colony structures in detect_mat using the Sato tubeness filter.

Computes a tubeness response from Hessian matrix eigenvalues at each specified scale, then takes the per-pixel maximum across all scales to produce a response map where bright ridges correspond to continuous filamentous structures. Intermediates are deleted between scales to reduce peak memory usage.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Thin filamentous colonies and mycelial networks (Aspergillus, Neurospora, streptomycetes).

• Continuous ridge-like morphologies that global thresholding misses.

• Branching or root-like colony forms requiring multi-scale detection.

• Plates where hyphal width varies across the image and a single sigma would miss structures at one end of the size range.

Consider Also:

• FocusEdgeFrangi when blob-versus-tube discrimination is needed via explicit alpha/beta sensitivity controls.

• FocusEdgeHessian for combined edge and ridge detection with adjustable background suppression.

• StructureSmoothing when anisotropic preprocessing is needed to reinforce coherent hyphal orientation before ridge detection.

Parameters:

• sigmas (tuple[float, ...]) – Scales (standard deviations in pixels) at which the Hessian is evaluated. Each sigma responds maximally to ridges whose cross-sectional half-width matches that value. The output is the per-pixel maximum across all scales, so extra sigmas can only raise the response. Typical tuple span: (1, 2, 3) for standard 300–600 dpi scans where hyphae are 2–8 px wide; extend to range(1, 10, 2) for thick mature filaments or lower magnification. A reasonable starting point for standard agar plate scans is to span the expected minimum and maximum hyphal width in pixels, e.g. (1, 3, 5) for 600 dpi images of Neurospora. Default: (1, 2, 3).

• black_ridges (bool) – Detect dark ridges on a bright background when True. False (default) detects bright ridges on a dark background, matching the detect_mat convention where colonies appear bright.

• mode (str) – Boundary handling for Gaussian derivative convolution. Accepted values: 'constant', 'reflect', 'wrap', 'nearest', 'mirror'. 'reflect' (default) mirrors image data at the border, minimising spurious ridge responses at plate edges. Use 'constant' (with cval set to the background level) only when stitching multi-tile acquisitions.

• cval (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Fill value used when mode='constant'. Has no effect for other border modes. Default: 0.

Returns:

Input image with detect_mat replaced by the Sato tubeness response map. Brighter pixels indicate stronger ridge-like structures at the sampled scales. rgb and gray are unchanged.

Return type:

Image

References

[1] Y. Sato et al., “Three-dimensional multi-scale line filter for segmentation and visualization of curvilinear structures in medical images,” Med. Image Anal., vol. 2, no. 2, pp. 143–168, Jun. 1998.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of ridge enhancement on plate images. What Enhancement Actually Does for background on Hessian-based ridge detection methods. Tutorial 10: Detecting Filamentous Fungi for filamentous fungi detection pipelines that use this enhancer.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

black_ridges: bool

cval: Annotated[float, TuneSpec(tunable=False)]

mode: str

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'black_ridges': FieldInfo(annotation=bool, required=False, default=False, description='Detect dark ridges on a bright background when ``True``. ``False`` (default) detects bright ridges on a dark background, matching the ``detect_mat`` convention where colonies appear bright.'), 'cval': FieldInfo(annotation=float, required=False, default=0, description="Fill value used when ``mode='constant'``. Has no effect for other border modes. Default: 0.", metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'mode': FieldInfo(annotation=str, required=False, default='reflect', description='Boundary handling for Gaussian derivative convolution. Accepted'), 'sigmas': FieldInfo(annotation=tuple[float, ...], required=False, default=(1, 2, 3), description='Scales (standard deviations in pixels) at which the Hessian is evaluated. Each sigma responds maximally to ridges whose cross-sectional half-width matches that value. The output is the per-pixel maximum across all scales, so extra sigmas can only raise the response. Typical tuple span: ``(1, 2, 3)`` for standard 300--600 dpi scans where hyphae are 2--8 px wide; extend to ``range(1, 10, 2)`` for thick mature filaments or lower magnification. A reasonable starting point for standard agar plate scans is to span the expected minimum and maximum hyphal width in pixels, e.g. ``(1, 3, 5)`` for 600 dpi images of Neurospora.')}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

sigmas: tuple[float, ...]

class phenotypic.enhance.FocusEdgeSobel

Bases: FocusEdge

Highlight colony edges in detect_mat using the Sobel gradient operator.

Computes the gradient magnitude across both image axes to emphasize intensity transitions at colony boundaries. The output is an edge-strength map suitable as a preprocessing step before watershed seeding or contour-based detectors, not a corrected grayscale image.

For how edge enhancement fits into the pipeline, see What Enhancement Actually Does.

Best For:

• Pre-filtering before watershed or contour-based colony detection.

• Separating touching colonies when combined with marker-based segmentation.

• Visualizing colony boundary sharpness for image quality assessment.

Consider Also:

• SharpenEdgeGauss when sharpening colony edges while retaining the original intensity profile rather than producing a pure gradient map.

• FocusEdgeLaplace for second-derivative edge detection that responds to ridges, valleys, and ring-like swarming fronts.

Returns:

Input image with detect_mat set to the Sobel gradient magnitude. rgb and gray are unchanged.

Return type:

Image

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of edge enhancement on plate images. What Enhancement Actually Does for how edge-response maps fit into the pipeline model.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

class phenotypic.enhance.GaussianBlur(*, sigma: Annotated[float, TuneSpec(low=0.5, high=5.0, step=None, log=True, categories=None, tunable=True)] = 2.0, mode: Literal['reflect', 'constant', 'nearest'] = 'reflect', cval: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0.0, truncate: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 4.0)

Bases: Smoothing

Smooth noise in detect_mat using isotropic Gaussian convolution.

Reduces high-frequency noise, scanner artefacts, and minor agar texture so that downstream thresholding responds to colony signal rather than local pixel variation. Colony edges become more coherent at the cost of some spatial sharpness; keeping sigma below the smallest colony radius avoids merging adjacent colonies.

For a comparison of denoising approaches, see What Enhancement Actually Does.

Best For:

• Plates with visible scanner CCD noise or agar granularity that triggers false positives in thresholding.

• Pre-filtering before edge-based detectors (Sobel, Canny) to reduce noise edges.

• Quick preprocessing when speed matters more than edge preservation.

Consider Also:

• MedianFilter when salt-and-pepper noise dominates and preserving sharp colony edges is important.

• LocalEdgeDenoise for bilateral smoothing within regions while keeping colony boundaries sharp.

• DenoiseBlockMatch for highest-quality BM3D denoising on critical low-light experiments.

Parameters:

• sigma (Annotated[float, TuneSpec(low=0.5, high=5.0, step=None, log=True, categories=None, tunable=True)]) – Standard deviation of the Gaussian kernel in pixels. Controls blur strength. Typical range: 0.5–5.0. Keep below the smallest colony radius to avoid merging adjacent colonies. Default: 2.0.

• mode (Literal['reflect', 'constant', 'nearest']) – Boundary handling strategy. Accepted values: 'reflect', 'constant', 'nearest'. Default: 'reflect'.

• cval (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Fill value used when mode='constant'. Default: 0.0.

• truncate (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Kernel half-width in standard deviations; the kernel extends truncate * sigma pixels from center. Larger values include more of the Gaussian tails with minimal quality improvement beyond 4.0. Default: 4.0.

Returns:

Input image with detect_mat smoothed by the Gaussian kernel. rgb and gray are unchanged.

Return type:

Image

Raises:

ValueError – If mode is not one of the accepted values.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of enhancement before detection. How To: Denoise Low-Light Images for a comparison of denoising methods on low-light plate images.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

cval: Annotated[float, TuneSpec(tunable=False)]

mode: Literal['reflect', 'constant', 'nearest']

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'cval': FieldInfo(annotation=float, required=False, default=0.0, description="Fill value used when ``mode='constant'``. Default: 0.0.", metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'mode': FieldInfo(annotation=Literal['reflect', 'constant', 'nearest'], required=False, default='reflect', description="Boundary handling strategy. Accepted values: ``'reflect'``, ``'constant'``, ``'nearest'``. Default: ``'reflect'``."), 'sigma': FieldInfo(annotation=float, required=False, default=2.0, description='Standard deviation of the Gaussian kernel in pixels. Controls blur strength. Typical range: 0.5--5.0. Keep below the smallest colony radius to avoid merging adjacent colonies. Default: 2.0.', metadata=[TuneSpec(low=0.5, high=5.0, step=None, log=True, categories=None, tunable=True)]), 'truncate': FieldInfo(annotation=float, required=False, default=4.0, description='Kernel half-width in standard deviations; the kernel extends ``truncate * sigma`` pixels from center. Larger values include more of the Gaussian tails with minimal quality improvement beyond 4.0.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

sigma: Annotated[float, TuneSpec(0.5, 5.0, log=True)]

truncate: Annotated[float, TuneSpec(tunable=False)]

class phenotypic.enhance.GrayOpening(*, shape: Literal['square', 'diamond', 'disk'] = 'square', width: Annotated[int, TuneSpec(low=3, high=15, step=2, log=False, categories=None, tunable=True)] = 5, n_iter: Annotated[int, TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)] = 1)

Bases: MorphologicalFiltering, FootprintMixin

Remove small bright artefacts from detect_mat via morphological opening.

Applies erosion followed by dilation with a structuring element, removing bright features whose spatial extent is smaller than the element while preserving larger colony structures. Effectively suppresses dust particles, small noise speckles, and tiny satellite colonies that would otherwise generate false detections.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Removing dust particles and small bright noise from plate scans before thresholding.

• Suppressing tiny satellite colonies or debris that would be counted as false positives by downstream detectors.

• Smoothing the detection surface before background subtraction to reduce artefact interference.

Consider Also:

• WhiteTophatEnhance when the goal is to isolate and enhance small bright structures rather than suppress them.

• SubtractWhiteTophat for subtracting small bright artefacts from the image while retaining the broader background.

• LocalEdgeDenoise for noise reduction that preserves colony edges without assuming a specific feature size.

Parameters:

• shape (Literal['square', 'diamond', 'disk']) – Structuring element geometry. Accepted values: 'square' (default, preserves axis-aligned edges), 'diamond' (rounded at diagonals), 'disk' (uniform circular neighbourhood). Default: 'square'.

• width (Annotated[int, TuneSpec(low=3, high=15, step=2, log=False, categories=None, tunable=True)]) – Diameter of the structuring element in pixels. Features smaller than width are removed. Typical range: 3–15. Default: 5.

• n_iter (Annotated[int, TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)]) – Number of times to apply the opening in sequence. Repeated opening with a small element produces smoother suppression than a single pass with a larger element. Default: 1.

Returns:

Input image with detect_mat morphologically opened. rgb and gray are unchanged.

Return type:

Image

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of enhancement pipelines on plate images. What Enhancement Actually Does for how morphological filtering fits into the pipeline model.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'n_iter': FieldInfo(annotation=int, required=False, default=1, description='Number of times to apply the opening in sequence. Repeated opening with a small element produces smoother suppression than a single pass with a larger element. Default: 1.', metadata=[TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)]), 'shape': FieldInfo(annotation=Literal['square', 'diamond', 'disk'], required=False, default='square', description="Structuring element geometry. Accepted values: ``'square'`` (default, preserves axis-aligned edges), ``'diamond'`` (rounded at diagonals), ``'disk'`` (uniform circular neighbourhood)."), 'width': FieldInfo(annotation=int, required=False, default=5, description='Diameter of the structuring element in pixels. Features smaller than ``width`` are removed. Typical range: 3--15. Default: 5.', metadata=[TuneSpec(low=3, high=15, step=2, log=False, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

n_iter: Annotated[int, TuneSpec(1, 3)]

shape: Literal['square', 'diamond', 'disk']

width: Annotated[int, TuneSpec(3, 15, step=2)]

class phenotypic.enhance.ImageInverter

Bases: ContrastAdjustment

Invert detect_mat pixel intensities so dark colonies become bright.

Reverses the brightness scale so dark regions become bright and vice versa. For uint8 data the inversion is 255 - pixel; for floating-point data it is max_value - pixel. Corrects for imaging systems or scan settings that produce colonies as dark regions on a bright background, restoring the bright-colony-on-dark-background convention expected by downstream detectors.

For how polarity correction fits into the pipeline, see What Enhancement Actually Does.

Best For:

• Correcting inverted scan output from imaging systems that produce dark-on-bright colony images.

• Preprocessing before detectors that assume bright colonies on dark agar backgrounds.

• Plates where colony boundaries are defined by dark absorption zones on a bright background.

Consider Also:

• SetDetectMode when switching the detection channel (e.g., to red or green) would resolve the contrast issue without polarity inversion.

• SharpenEdgeGauss when the issue is low contrast rather than inverted polarity.

Returns:

Input image with detect_mat intensity-inverted. rgb and gray are unchanged.

Return type:

Image

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of enhancement pipelines on plate images. What Enhancement Actually Does for how the detect_mat polarity convention is established.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

class phenotypic.enhance.LocalEdgeDenoise(*, use_gat: bool = False, gat_gain: Annotated[float, Gt(gt=0)] = 1.0, gat_mu: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0.0, gat_read_sigma: Annotated[float, Ge(ge=0)] = 0.0, gat_scale_factor: Annotated[float | None, Gt(gt=0)] = None, sigma_color: Annotated[float | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, 0.02, 0.05, 0.1, 0.2, 0.5, tunable=True)] = None, sigma_spatial: Annotated[float, Gt(gt=0.0), TuneSpec(low=1.0, high=50.0, step=None, log=True, categories=None, tunable=True)] = 15, win_size: Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, mode: Literal['constant', 'edge', 'symmetric', 'reflect', 'wrap'] = 'constant', cval: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0, clip: bool = True)

Bases: _GATSupportMixin, ImageDenoiser

Denoise detect_mat with local edge-preserving bilateral filtering.

Weights each pixel by both spatial proximity and intensity similarity within a local neighbourhood, smoothing uniform agar regions while keeping colony boundaries sharp. The optimal intensity range weight scales linearly with the image noise floor, so noisier images benefit from a larger sigma_color.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Noisy or grainy agar scans from high-ISO photography or older flatbed scanners where colony edges must remain sharp.

• Plates with surface condensation, dust speckles, or uneven agar texture.

• Fast single-pass preprocessing before thresholding when only local smoothing is needed.

• Low-quality captures where colony morphology must be preserved.

Consider Also:

• NonLocalMeansDenoiser when repetitive agar texture warrants whole-image patch search for stronger denoising.

• EnhanceBlockMatch for state-of-the-art structured noise removal at higher computational cost.

• SubtractGaussian when the primary problem is a slow-varying illumination gradient rather than pixel-level noise.

Parameters:

• sigma_color (Annotated[float | None, TuneSpec(low=None, high=None, step=None, log=False, categories=(None, 0.02, 0.05, 0.1, 0.2, 0.5), tunable=True)]) – Intensity similarity weighting on the [0, 1] scale. Small values (0.02–0.05) preserve subtle colony boundaries; medium values (0.05–0.15) balance denoising and edge preservation; large values (0.2–0.5) smooth aggressively across edges. None (default) auto-estimates from the image standard deviation. The optimal value is approximately proportional to the noise standard deviation of the image. Automatically retargeted to 1.0 when use_gat=True.

• sigma_spatial (Annotated[float, Gt(gt=0.0), TuneSpec(low=1.0, high=50.0, step=None, log=True, categories=None, tunable=True)]) – Spatial distance weighting in pixels. Small values (1–5) apply local denoising only; medium values (10–20) smooth regionally; large values (30–50) blend wide areas. Keep below the minimum colony diameter to avoid smearing adjacent colonies together. Default: 15.

• win_size (Annotated[int | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Filter window half-size in pixels. None (default) auto-computes as max(5, 2*ceil(3*sigma_spatial)+1). Override only to cap memory use when sigma_spatial is very large.

• mode (Literal['constant', 'edge', 'symmetric', 'reflect', 'wrap']) – Boundary handling. Accepted values: 'constant', 'edge', 'symmetric', 'reflect', 'wrap'. 'constant' (default) pads with cval; 'edge' or 'reflect' avoids darkening at plate borders when the plate fills the frame.

• cval (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Fill value used when mode='constant'. Set to the mean background intensity to suppress spurious dark-band artefacts at plate edges. Default: 0.0.

• clip (bool) – Clip output to [0, 1]. Default: True. Automatically deferred to False when use_gat=True.

• parameters (# GAT)

• use_gat (bool) – Wrap denoising in the Generalized Anscombe Transform to stabilize Poisson-Gaussian noise variance before filtering. Most beneficial for low-light photographs or low-exposure scans where shot noise dominates. Default: False.

• gat_gain (Annotated[float, Gt(gt=0)]) – Camera gain in electrons per ADU. Scales the Poisson noise component in the GAT model. Typical range 0.1–10.0; leave at 1.0 for normalized images without calibrated gain. Default: 1.0.

• gat_mu (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Read-noise mean (baseline DC offset). Set to zero if dark-frame subtraction has already been applied. Default: 0.0.

• gat_read_sigma (Annotated[float, Ge(ge=0)]) – Standard deviation of additive Gaussian read noise. 0.0 (default) assumes pure Poisson noise. Typical flatbed scanner values: 0.004–0.02 on the [0, 1] scale.

• gat_scale_factor (Annotated[float | None, Gt(gt=0)]) – Multiplier converting normalized [0, 1] data to photon counts before the GAT forward pass. None (default) auto-detects from image bit depth (8-bit → 255, 16-bit → 65535).

Returns:

Input image with detect_mat smoothed by bilateral filtering. rgb and gray are unchanged.

Return type:

Image

References

[1] C. Tomasi and R. Manduchi, “Bilateral filtering for gray and color images,” in Proc. ICCV, Bombay, 1998, pp. 839–846. [2] M. Mäkitalo and A. Foi, “Optimal inversion of the generalized Anscombe transformation for Poisson-Gaussian noise,” IEEE Trans. Image Process., vol. 22, no. 1, pp. 91–103, Jan. 2013.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of denoising pipelines on plate images. How To: Denoise Low-Light Images for edge-preserving denoising strategies on low-light plate images. What Enhancement Actually Does for bilateral filter theory and parameter selection guidance.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

clip: bool

cval: Annotated[float, TuneSpec(tunable=False)]

gat_gain: float

gat_mu: Annotated[float, TuneSpec(tunable=False)]

gat_read_sigma: float

gat_scale_factor: float | None

mode: Literal['constant', 'edge', 'symmetric', 'reflect', 'wrap']

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'clip': FieldInfo(annotation=bool, required=False, default=True, description='Clip output to [0, 1]. Default: ``True``. Automatically deferred to ``False`` when ``use_gat=True``. # GAT parameters (active only when use_gat=True)'), 'cval': FieldInfo(annotation=float, required=False, default=0, description="Fill value used when ``mode='constant'``. Set to the mean background intensity to suppress spurious dark-band artefacts at plate edges. Default: 0.0.", metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'gat_gain': FieldInfo(annotation=float, required=False, default=1.0, description='Camera gain in electrons per ADU. Scales the Poisson noise component in the GAT model. Typical range 0.1--10.0; leave at 1.0 for normalized images without calibrated gain.', metadata=[Gt(gt=0)]), 'gat_mu': FieldInfo(annotation=float, required=False, default=0.0, description='Read-noise mean (baseline DC offset). Set to zero if dark-frame subtraction has already been applied. Default: 0.0.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'gat_read_sigma': FieldInfo(annotation=float, required=False, default=0.0, description='Standard deviation of additive Gaussian read noise. ``0.0`` (default) assumes pure Poisson noise. Typical flatbed scanner values: 0.004--0.02 on the [0, 1] scale.', metadata=[Ge(ge=0)]), 'gat_scale_factor': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Multiplier converting normalized [0, 1] data to photon counts before the GAT forward pass. ``None`` (default) auto-detects from image bit depth (8-bit → 255, 16-bit → 65535).', metadata=[Gt(gt=0)]), 'mode': FieldInfo(annotation=Literal['constant', 'edge', 'symmetric', 'reflect', 'wrap'], required=False, default='constant', description="Boundary handling. Accepted values: ``'constant'``, ``'edge'``, ``'symmetric'``, ``'reflect'``, ``'wrap'``. ``'constant'`` (default) pads with ``cval``; ``'edge'`` or ``'reflect'`` avoids darkening at plate borders when the plate fills the frame."), 'sigma_color': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Intensity similarity weighting on the [0, 1] scale. Small values (0.02--0.05) preserve subtle colony boundaries; medium values (0.05--0.15) balance denoising and edge preservation; large values (0.2--0.5) smooth aggressively across edges. ``None`` (default) auto-estimates from the image standard deviation. The optimal value is approximately proportional to the noise standard deviation of the image. Automatically retargeted to 1.0 when ``use_gat=True``.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=(None, 0.02, 0.05, 0.1, 0.2, 0.5), tunable=True)]), 'sigma_spatial': FieldInfo(annotation=float, required=False, default=15, description='Spatial distance weighting in pixels. Small values (1--5) apply local denoising only; medium values (10--20) smooth regionally; large values (30--50) blend wide areas. Keep below the minimum colony diameter to avoid smearing adjacent colonies together. Default: 15.', metadata=[Gt(gt=0.0), TuneSpec(low=1.0, high=50.0, step=None, log=True, categories=None, tunable=True)]), 'use_gat': FieldInfo(annotation=bool, required=False, default=False, description='Wrap denoising in the Generalized Anscombe Transform to stabilize Poisson-Gaussian noise variance before filtering. Most beneficial for low-light photographs or low-exposure scans where shot noise dominates. Default: ``False``.'), 'win_size': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Filter window half-size in pixels. ``None`` (default) auto-computes as ``max(5, 2*ceil(3*sigma_spatial)+1)``. Override only to cap memory use when ``sigma_spatial`` is very large.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

sigma_color: Annotated[float | None, TuneSpec(categories=[None, 0.02, 0.05, 0.1, 0.2, 0.5])]

sigma_spatial: Annotated[float, TuneSpec(1.0, 50.0, log=True)]

use_gat: bool

win_size: Annotated[int | None, TuneSpec(tunable=False)]

class phenotypic.enhance.MedianFilter(*, mode: Literal['nearest', 'reflect', 'constant', 'mirror', 'wrap'] = 'nearest', shape: Literal['disk', 'square', 'diamond'] | None = None, width: Annotated[int, TuneSpec(low=3, high=9, step=2, log=False, categories=None, tunable=True)] = 5, cval: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0.0)

Bases: Smoothing

Remove impulsive noise from detect_mat while preserving colony edges.

Replaces each pixel with the median of its local neighbourhood, making it robust to outlier pixels such as condensation droplets, dust specks, and sensor noise spikes. Preserves colony boundaries more faithfully than Gaussian smoothing because the median operation does not average intensity across edges.

For a comparison of denoising approaches, see What Enhancement Actually Does.

Best For:

• Plates with salt-and-pepper noise or isolated bright/dark speckle artefacts from scanner CCD defects or condensation.

• Preserving sharp colony boundary edges during denoising before edge-based detection.

• Pre-filtering before edge-based detectors (Canny, Sobel) where noise edges must be suppressed without blurring colony margins.

Consider Also:

• GaussianBlur for faster, simpler smoothing when edge preservation is less critical and noise is Gaussian rather than impulsive.

• LocalEdgeDenoise for bilateral edge-preserving smoothing with continuous intensity gradients.

• RankMedianEnhancer for configurable rank-based filtering with explicit footprint control.

Parameters:

• mode (Literal['nearest', 'reflect', 'constant', 'mirror', 'wrap']) – Boundary handling strategy. Accepted values: 'nearest', 'reflect', 'constant', 'mirror', 'wrap'. Default: 'nearest'.

• shape (Literal['disk', 'square', 'diamond'] | None) – Structuring element shape for the median neighbourhood. Accepted values: 'disk', 'square', 'diamond', or None for the library default footprint. Default: None.

• width (Annotated[int, TuneSpec(low=3, high=9, step=2, log=False, categories=None, tunable=True)]) – Size of the structuring element in pixels. Larger values smooth more aggressively. Typical range: 3–9. Default: 5.

• cval (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Fill value used when mode='constant'. Default: 0.0.

Returns:

Input image with detect_mat filtered. rgb and gray are unchanged.

Return type:

Image

See also

How To: Denoise Low-Light Images for a comparison of denoising methods on low-light plate images. What Enhancement Actually Does for how enhancement fits into the pipeline model.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

cval: Annotated[float, TuneSpec(tunable=False)]

mode: Literal['nearest', 'reflect', 'constant', 'mirror', 'wrap']

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'cval': FieldInfo(annotation=float, required=False, default=0.0, description="Fill value used when ``mode='constant'``. Default: 0.0.", metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'mode': FieldInfo(annotation=Literal['nearest', 'reflect', 'constant', 'mirror', 'wrap'], required=False, default='nearest', description="Boundary handling strategy. Accepted values: ``'nearest'``, ``'reflect'``, ``'constant'``, ``'mirror'``, ``'wrap'``."), 'shape': FieldInfo(annotation=Union[Literal['disk', 'square', 'diamond'], NoneType], required=False, default=None, description="Structuring element shape for the median neighbourhood. Accepted values: ``'disk'``, ``'square'``, ``'diamond'``, or ``None`` for the library default footprint. Default: ``None``."), 'width': FieldInfo(annotation=int, required=False, default=5, description='Size of the structuring element in pixels. Larger values smooth more aggressively. Typical range: 3--9. Default: 5.', metadata=[TuneSpec(low=3, high=9, step=2, log=False, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

shape: Literal['disk', 'square', 'diamond'] | None

width: Annotated[int, TuneSpec(3, 9, step=2)]

class phenotypic.enhance.NonLocalMeansDenoiser(*, use_gat: bool = False, gat_gain: Annotated[float, Gt(gt=0)] = 1.0, gat_mu: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0.0, gat_read_sigma: Annotated[float, Ge(ge=0)] = 0.0, gat_scale_factor: Annotated[float | None, Gt(gt=0)] = None, patch_size: Annotated[int, TuneSpec(low=5, high=15, step=2, log=False, categories=None, tunable=True)] = 5, search_dist: Annotated[int, TuneSpec(low=5, high=21, step=2, log=False, categories=None, tunable=True)] = 11, h: Annotated[float, TuneSpec(low=0.1, high=2.0, step=None, log=True, categories=None, tunable=True)] = 0.5, fast_mode: bool = False, sigma: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0.0)

Bases: _GATSupportMixin, ImageDenoiser

Denoise detect_mat with non-local means patch-based filtering.

Compares small patches across the entire image to identify structurally similar regions and averages them, exploiting the repetitive texture of arrayed colony plates to remove noise while preserving thin colony boundaries. Stronger than bilateral filtering for images with repetitive agar background patterns, at higher computational cost.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Scanner noise and agar granularity where colony edges must stay sharp.

• Low-contrast or faint colonies where Gaussian blur would cause loss of detail.

• Dense arrayed plates whose repetitive colony pattern provides many similar patches for effective averaging.

• Pre-filtering before edge detection to reduce noise without amplifying gradients.

Consider Also:

• EnhanceBlockMatch for state-of-the-art structured noise removal at higher computational cost.

• LocalEdgeDenoise for faster edge-preserving denoising without whole-image patch search.

• BayesShrinkEnhancer for adaptive wavelet denoising that applies spatially varying thresholds.

Parameters:

• patch_size (Annotated[int, TuneSpec(low=5, high=15, step=2, log=False, categories=None, tunable=True)]) – Side length of the square patches compared during denoising in pixels. Larger patches capture more structural context and suppress noise more robustly, but are slower and risk spanning adjacent colony boundaries on dense plates. Typical range: 3–11 (skimage library default is 7); keep ≤ 5 for fine hyphal structures to avoid cross-branch averaging. Default: 5.

• search_dist (Annotated[int, TuneSpec(low=5, high=21, step=2, log=False, categories=None, tunable=True)]) – Half-side of the square search window for patch candidates. Larger values find more similar patches at quadratic computational cost (the skimage library default is 11, i.e. a 23x23 window). On crowded 384-well plates a smaller value (5–7) avoids pulling patches from neighbouring colony positions. Default: 11.

• h (Annotated[float, TuneSpec(low=0.1, high=2.0, step=None, log=True, categories=None, tunable=True)]) – Cut-off distance in the patch-similarity weight kernel. Patches with squared distance greater than h squared receive exponentially diminished weight. Rule of thumb: h approximately equals the noise standard deviation. Both h and sigma are automatically retargeted to 1.0 when use_gat=True. Default: 0.5.

• fast_mode (bool) – If True, use the faster uniform-weight variant (integral-image algorithm); if False (default), use the original Gaussian-weighted algorithm which preserves colony edges marginally better. When sigma is provided, pair fast_mode=True with h ≈ 0.8 * sigma and fast_mode=False with h ≈ 0.6 * sigma. Default: False.

• sigma (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Known noise standard deviation on the [0, 1] scale. When > 0, noise variance is subtracted from patch distances, improving weight accuracy for structurally similar patches. Set to 0.0 to disable. Retargeted to 1.0 when use_gat=True. Default: 0.0.

• parameters (# GAT)

• use_gat (bool) – Wrap denoising in the Generalized Anscombe Transform to handle Poisson-Gaussian noise (e.g., low-light fluorescence images of colonies). Default: False.

• gat_gain (Annotated[float, Gt(gt=0)]) – Camera gain in electrons per ADU. Scales the Poisson noise component. Typical range 0.1–10.0; leave at 1.0 for normalized images without calibrated gain. Default: 1.0.

• gat_mu (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Read-noise mean (baseline DC offset). Set to 0.0 if dark-frame subtraction has been applied. Default: 0.0.

• gat_read_sigma (Annotated[float, Ge(ge=0)]) – Standard deviation of additive Gaussian read noise on the [0, 1] scale. 0.0 (default) assumes pure Poisson noise. Scientific CMOS cameras: typically 0.001–0.05.

• gat_scale_factor (Annotated[float | None, Gt(gt=0)]) – Multiplier converting normalized [0, 1] data to photon counts before the GAT forward pass. None (default) auto-detects from image bit depth (8-bit → 255, 16-bit → 65535).

Returns:

Input image with detect_mat denoised via non-local means filtering. rgb and gray are unchanged.

Return type:

Image

References

[1] A. Buades, B. Coll, and J.-M. Morel, “A non-local algorithm for image denoising,” in Proc. CVPR, vol. 2, 2005, pp. 60–65. [2] M. Lebrun, “Non-local means denoising,” Image Process. On Line, vol. 2012, pp. 208–212, 2012. [3] M. Mäkitalo and A. Foi, “Optimal inversion of the generalized Anscombe transformation for Poisson-Gaussian noise,” IEEE Trans. Image Process., vol. 22, no. 1, pp. 91–103, Jan. 2013.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of denoising pipelines on plate images. How To: Denoise Low-Light Images for non-local means and other denoising strategies on low-light plate images. What Enhancement Actually Does for patch-similarity denoising theory and parameter selection guidance.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

fast_mode: bool

gat_gain: float

gat_mu: Annotated[float, TuneSpec(tunable=False)]

gat_read_sigma: float

gat_scale_factor: float | None

h: Annotated[float, TuneSpec(0.1, 2.0, log=True)]

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'fast_mode': FieldInfo(annotation=bool, required=False, default=False, description='If ``True``, use the faster uniform-weight variant (integral-image algorithm); if ``False`` (default), use the original Gaussian-weighted algorithm which preserves colony edges marginally better. When ``sigma`` is provided, pair ``fast_mode=True`` with ``h ≈ 0.8 * sigma`` and ``fast_mode=False`` with ``h ≈ 0.6 * sigma``. Default: ``False``.'), 'gat_gain': FieldInfo(annotation=float, required=False, default=1.0, description='Camera gain in electrons per ADU. Scales the Poisson noise component. Typical range 0.1--10.0; leave at 1.0 for normalized images without calibrated gain. Default: 1.0.', metadata=[Gt(gt=0)]), 'gat_mu': FieldInfo(annotation=float, required=False, default=0.0, description='Read-noise mean (baseline DC offset). Set to 0.0 if dark-frame subtraction has been applied. Default: 0.0.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'gat_read_sigma': FieldInfo(annotation=float, required=False, default=0.0, description='Standard deviation of additive Gaussian read noise on the [0, 1] scale. ``0.0`` (default) assumes pure Poisson noise. Scientific CMOS cameras: typically 0.001--0.05.', metadata=[Ge(ge=0)]), 'gat_scale_factor': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Multiplier converting normalized [0, 1] data to photon counts before the GAT forward pass. ``None`` (default) auto-detects from image bit depth (8-bit → 255, 16-bit → 65535).', metadata=[Gt(gt=0)]), 'h': FieldInfo(annotation=float, required=False, default=0.5, description='Cut-off distance in the patch-similarity weight kernel. Patches with squared distance greater than ``h`` squared receive exponentially diminished weight. Rule of thumb: ``h`` approximately equals the noise standard deviation. Both ``h`` and ``sigma`` are automatically retargeted to 1.0 when ``use_gat=True``. Default: 0.5.', metadata=[TuneSpec(low=0.1, high=2.0, step=None, log=True, categories=None, tunable=True)]), 'patch_size': FieldInfo(annotation=int, required=False, default=5, description='Side length of the square patches compared during denoising in pixels. Larger patches capture more structural context and suppress noise more robustly, but are slower and risk spanning adjacent colony boundaries on dense plates. Typical range: 3--11 (skimage library default is 7); keep ≤ 5 for fine hyphal structures to avoid cross-branch averaging. Default: 5.', metadata=[TuneSpec(low=5, high=15, step=2, log=False, categories=None, tunable=True)]), 'search_dist': FieldInfo(annotation=int, required=False, default=11, description='Half-side of the square search window for patch candidates. Larger values find more similar patches at quadratic computational cost (the skimage library default is 11, i.e. a 23x23 window). On crowded 384-well plates a smaller value (5--7) avoids pulling patches from neighbouring colony positions. Default: 11.', metadata=[TuneSpec(low=5, high=21, step=2, log=False, categories=None, tunable=True)]), 'sigma': FieldInfo(annotation=float, required=False, default=0.0, description='Known noise standard deviation on the [0, 1] scale. When > 0, noise variance is subtracted from patch distances, improving weight accuracy for structurally similar patches. Set to 0.0 to disable. Retargeted to 1.0 when ``use_gat=True``. Default: 0.0. # GAT parameters (active only when use_gat=True)', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'use_gat': FieldInfo(annotation=bool, required=False, default=False, description='Wrap denoising in the Generalized Anscombe Transform to handle Poisson-Gaussian noise (e.g., low-light fluorescence images of colonies). Default: ``False``.')}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

patch_size: Annotated[int, TuneSpec(5, 15, step=2)]

search_dist: Annotated[int, TuneSpec(5, 21, step=2)]

sigma: Annotated[float, TuneSpec(tunable=False)]

use_gat: bool

class phenotypic.enhance.RankMedianEnhancer(*, shape: str = 'square', width: Annotated[int | None, TuneSpec(low=3, high=15, step=2, log=False, categories=None, tunable=True)] = None, shift_x: Annotated[int, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0, shift_y: Annotated[int, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0)

Bases: Smoothing

Suppress impulsive noise in detect_mat with rank-based median filtering.

Applies a local median using rank filters with a configurable structuring element shape and size. Effectively removes salt-and-pepper noise, dust speckles, and pixel-level artifacts while preserving colony boundaries when the footprint is smaller than the minimum colony diameter.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Salt-and-pepper or impulsive noise from sensor defects or scanner CCD artifacts.

• Dust speckles and pixel-level artifacts on scanned plates.

• Grid-like imaging artifacts where a 'square' footprint aligns with the noise geometry.

• Pre-detection cleanup before applying a threshold-based detector.

Consider Also:

• LocalEdgeDenoise for edge-preserving smoothing of Gaussian noise without the uint8 conversion required by rank filters.

• NonLocalMeansDenoiser for patch-based denoising that preserves fine colony texture better on noisy plates.

• GrayOpening for morphological artifact removal that does not require uint8 quantization.

Parameters:

• shape (str) – Footprint geometry. Accepted values: 'disk' for isotropic smoothing suited to round colonies; 'square' (default) to align with grid-pattern sensor artifacts.

• width (Annotated[int | None, TuneSpec(low=3, high=15, step=2, log=False, categories=None, tunable=True)]) – Footprint width in pixels. Set smaller than the minimum colony diameter to preserve colony edges. None (default) auto-derives a small value as approximately 0.2 % of the shorter image dimension.

• shift_x (Annotated[int, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Horizontal offset of the footprint centre in pixels. Non-zero values shift the filter kernel to correct for directional streak artefacts. Default: 0.

• shift_y (Annotated[int, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Vertical offset of the footprint centre in pixels. Non-zero values shift the filter kernel to correct for directional streak artefacts. Default: 0.

Returns:

Input image with detect_mat median-filtered. rgb and gray are unchanged.

Return type:

Image

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of denoising pipelines on plate images. What Enhancement Actually Does for background on rank filtering and its role in colony detection pipelines.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'shape': FieldInfo(annotation=str, required=False, default='square', description="Footprint geometry. Accepted values: ``'disk'`` for isotropic smoothing suited to round colonies; ``'square'`` (default) to align with grid-pattern sensor artifacts."), 'shift_x': FieldInfo(annotation=int, required=False, default=0, description='Horizontal offset of the footprint centre in pixels. Non-zero values shift the filter kernel to correct for directional streak artefacts. Default: 0.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'shift_y': FieldInfo(annotation=int, required=False, default=0, description='Vertical offset of the footprint centre in pixels. Non-zero values shift the filter kernel to correct for directional streak artefacts. Default: 0.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'width': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Footprint width in pixels. Set smaller than the minimum colony diameter to preserve colony edges. ``None`` (default) auto-derives a small value as approximately 0.2 % of the shorter image dimension.', metadata=[TuneSpec(low=3, high=15, step=2, log=False, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

shape: str

shift_x: Annotated[int, TuneSpec(tunable=False)]

shift_y: Annotated[int, TuneSpec(tunable=False)]

width: Annotated[int | None, TuneSpec(3, 15, step=2)]

class phenotypic.enhance.SetDetectMode(*, mode: Literal['gray', 'red', 'green', 'blue', 'MinRGB', 'LabL', 'LabA', 'LabB', 'HsvS', 'HsvV', 'InvS'] = 'gray')

Bases: ImageOperation

Switch the detection matrix source channel mid-pipeline.

Resets detect_mat to a fresh copy of the chosen channel, discarding any enhancements applied so far. Useful when different pipeline stages need to operate on different color channels or when a specific channel provides superior colony-background contrast for downstream detection.

For background on channel selection, see What Enhancement Actually Does.

Best For:

• Plates where colonies are more visible in a single color channel than in grayscale (e.g., pigmented yeast on agar).

• Switching to a specific channel (such as red or green) that provides stronger colony-background contrast.

• Resetting enhancements mid-pipeline to start fresh on a different channel for a later detection stage.

Consider Also:

• ImageInverter when the issue is inverted intensity polarity rather than channel selection.

Parameters:

mode (Literal['gray', 'red', 'green', 'blue', 'MinRGB', 'LabL', 'LabA', 'LabB', 'HsvS', 'HsvV', 'InvS']) – Channel to use as the detection matrix. Accepted values: 'gray' (default), 'red', 'green', 'blue', 'MinRGB' (per-pixel minimum across R/G/B), 'LabL', 'LabA', 'LabB', 'HsvS', 'HsvV', 'InvS'.

Returns:

Input image with detect_mode and detect_mat updated to the chosen channel. Prior enhancements to detect_mat are discarded.

Return type:

Image

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of channel selection strategies on plate images.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image: Image, inplace=False) → Image

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

mode: DetectMode

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'mode': FieldInfo(annotation=Literal['gray', 'red', 'green', 'blue', 'MinRGB', 'LabL', 'LabA', 'LabB', 'HsvS', 'HsvV', 'InvS'], required=False, default='gray', description="Channel to use as the detection matrix. Accepted values: ``'gray'`` (default), ``'red'``, ``'green'``, ``'blue'``, ``'MinRGB'`` (per-pixel minimum across R/G/B), ``'LabL'``, ``'LabA'``, ``'LabB'``, ``'HsvS'``, ``'HsvV'``, ``'InvS'``.")}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

class phenotypic.enhance.SharpenEdgeGauss(*, radius: Annotated[float, Gt(gt=0.0), TuneSpec(low=0.5, high=15.0, step=None, log=True, categories=None, tunable=True)] = 2.0, amount: Annotated[float, TuneSpec(low=0.3, high=2.0, step=None, log=False, categories=None, tunable=True)] = 1.0, preserve_range: bool = False, n_iter: Annotated[int, Ge(ge=1), TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)] = 1)

Bases: ContrastAdjustment

Sharpen colony edges in detect_mat with unsharp masking.

Subtracts a Gaussian-blurred copy from the original and scales the difference to emphasize high-contrast boundaries. Makes soft or indistinct colony edges more pronounced, improving thresholding and edge-detection accuracy downstream.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Colonies with soft, gradual edges caused by translucent growth or slight scanner blur.

• Dense plates where colony boundaries blend gradually into the agar background.

• Pre-threshold sharpening to improve segmentation accuracy on mildly blurred images.

• Plates with slight lens or scanner defocus that softens colony boundaries.

Consider Also:

• LocalEdgeDenoise for denoising before sharpening on grainy images, to avoid amplifying noise alongside edges.

• FocusEdgeLaplace for second-derivative edge detection that replaces rather than enhances the intensity profile.

• FocusEdgePhase for contrast-invariant edge detection under uneven illumination.

Parameters:

• radius (Annotated[float, Gt(gt=0.0), TuneSpec(low=0.5, high=15.0, step=None, log=True, categories=None, tunable=True)]) – Standard deviation of the Gaussian blur kernel in pixels. Controls the spatial scale of features enhanced. Typical range: 0.5–5.0 for fine colony edges; up to 15 for broader low-frequency enhancement. Default: 2.0.

• amount (Annotated[float, TuneSpec(low=0.3, high=2.0, step=None, log=False, categories=None, tunable=True)]) – Strength multiplier for the sharpening effect. Values below 1.0 produce subtle enhancement; 1.0–1.5 gives moderate sharpening; values above 2.0 risk halo artifacts along high-contrast edges. Default: 1.0.

• preserve_range (bool) – Preserve the input pixel value range during filtering. Set True when the downstream operation requires values within the original bounds. Default: False.

• n_iter (Annotated[int, Ge(ge=1), TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)]) – Number of successive sharpening passes. Each pass compounds the effect. Typical range: 1–3. Default: 1.

Returns:

Input image with detect_mat sharpened via unsharp masking. rgb and gray are unchanged.

Return type:

Image

Raises:

• ValueError – If radius is not positive.

• ValueError – If n_iter is less than 1.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of edge sharpening on plate images. What Enhancement Actually Does for background on unsharp masking and sharpening strategies.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

amount: Annotated[float, TuneSpec(0.3, 2.0)]

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'amount': FieldInfo(annotation=float, required=False, default=1.0, description='Strength multiplier for the sharpening effect. Values below 1.0 produce subtle enhancement; 1.0--1.5 gives moderate sharpening; values above 2.0 risk halo artifacts along high-contrast edges. Default: 1.0.', metadata=[TuneSpec(low=0.3, high=2.0, step=None, log=False, categories=None, tunable=True)]), 'n_iter': FieldInfo(annotation=int, required=False, default=1, description='Number of successive sharpening passes. Each pass compounds the effect. Typical range: 1--3. Default: 1.', metadata=[Ge(ge=1), TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)]), 'preserve_range': FieldInfo(annotation=bool, required=False, default=False, description='Preserve the input pixel value range during filtering. Set ``True`` when the downstream operation requires values within the original bounds. Default: ``False``.'), 'radius': FieldInfo(annotation=float, required=False, default=2.0, description='Standard deviation of the Gaussian blur kernel in pixels. Controls the spatial scale of features enhanced. Typical', metadata=[Gt(gt=0.0), TuneSpec(low=0.5, high=15.0, step=None, log=True, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

n_iter: Annotated[int, TuneSpec(1, 3)]

preserve_range: bool

radius: Annotated[float, TuneSpec(0.5, 15.0, log=True)]

class phenotypic.enhance.StructureSmoothing(*, num_iter: Annotated[int, TuneSpec(low=15, high=30, step=None, log=False, categories=None, tunable=True)] = 20, sigma: Annotated[float, TuneSpec(low=0.5, high=5.0, step=None, log=True, categories=None, tunable=True)] = 1.5, rho: Annotated[float | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = None, dt: Annotated[float, TuneSpec(low=0.05, high=0.125, step=None, log=False, categories=None, tunable=True)] = 0.1, alpha: float = 0.001, C: float = 99.0)

Bases: Smoothing

Enhance filamentous structures in detect_mat via coherence-enhancing anisotropic diffusion.

Iteratively smooths the image preferentially along locally coherent orientations while suppressing diffusion across boundaries. A two-scale structure tensor (noise scale sigma, integration scale rho) estimates local orientation at each step, and the diffusion tensor is oriented to follow elongated features such as fungal hyphae, streak inoculations, and branching colony morphologies.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Filamentous fungal hyphae (Aspergillus, Penicillium, molds) where branching mycelial networks need reinforcement before ridge detection.

• Streak inoculation patterns where colonies grow along lines.

• Preprocessing before FocusEdgeSato, FocusEdgeFrangi, or FocusEdgeMeijering to reduce noise without erasing tubular structures.

• Faint elongated features in low-contrast or noisy plate scans.

Consider Also:

• LocalEdgeDenoise for isotropic edge-preserving denoising of round colonies where directional enhancement is not needed.

• FocusEdgeSato for direct ridge detection on images that are already clean enough to skip a diffusion preprocessing step.

• GaussianBlur when isotropic smoothing is sufficient and directional selectivity is not required.

Parameters:

• num_iter (Annotated[int, TuneSpec(low=15, high=30, step=None, log=False, categories=None, tunable=True)]) – Number of diffusion iterations. Each iteration advances the PDE one time step of size dt; the total diffusion extent is proportional to num_iter * dt. Typical range: 5–100; values 15–30 are the practical working range for most plate-scan images. Default: 20.

• sigma (Annotated[float, TuneSpec(low=0.5, high=5.0, step=None, log=True, categories=None, tunable=True)]) – Noise scale for Gaussian derivative computation in pixels. Sets the spatial frequency band at which local orientation is estimated. Match to the half-width of structures to enhance: fine hyphae (< 3 px) need sigma 0.5–1.0; thick ridges or streak bands tolerate 2–4. Typical range: 0.5–5.0. Default: 1.5.

• rho (Annotated[float | None, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Integration scale for structure tensor smoothing in pixels. Averaging the outer-product tensor over rho produces a smoother orientation field that follows gently curving structures. Must be >= sigma. None (default) sets rho = sigma (single-scale mode). Typical values: 2–3x sigma; use values close to sigma for tight-turning branching mycelium and larger values for long straight streaks.

• dt (Annotated[float, TuneSpec(low=0.05, high=0.125, step=None, log=False, categories=None, tunable=True)]) – Time step per diffusion iteration. Must satisfy the 2D forward-Euler stability bound (dt <= 0.125). The extent of smoothing is governed by the total diffusion time T = num_iter * dt, so prefer adjusting num_iter rather than dt when tuning effect magnitude. Typical range: 0.05–0.125. Default: 0.1.

• alpha (float) – Minimum diffusivity coefficient (0 < alpha < 1). Prevents the perpendicular-to-structure diffusivity from collapsing to zero and maximises anisotropy at small values (0.001); larger values (0.01–0.1) add isotropic regularisation. Default: 0.001.

• C (float) – Percentile of the initial coherence histogram used as the adaptive contrast threshold (0 < C <= 100). High values (95–99) restrict anisotropic diffusion to only the most coherent pixels; lower values (70–90) spread it to weaker elongated structures. Default: 99.

Returns:

Input image with detect_mat smoothed along coherent structures. rgb and gray are unchanged.

Return type:

Image

Raises:

ValueError – If num_iter < 1, dt is not in (0, 0.125], sigma <= 0, rho < sigma, alpha not in (0, 1), or C not in (0, 100].

References

[1] J. Weickert, “Coherence-enhancing diffusion filtering,” Int. J. Comput. Vis., vol. 31, no. 2/3, pp. 111–127, Apr. 1999.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of enhancement pipelines on plate images. Tutorial 10: Detecting Filamentous Fungi for pipelines that use this enhancer before ridge detection. What Enhancement Actually Does for background on anisotropic diffusion and the structure tensor.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

C: float

alpha: float

dt: Annotated[float, TuneSpec(0.05, 0.125)]

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'C': FieldInfo(annotation=float, required=False, default=99.0, description='Percentile of the initial coherence histogram used as the adaptive contrast threshold (0 < C <= 100). High values (95--99) restrict anisotropic diffusion to only the most coherent pixels; lower values (70--90) spread it to weaker elongated structures.'), 'alpha': FieldInfo(annotation=float, required=False, default=0.001, description='Minimum diffusivity coefficient (0 < alpha < 1). Prevents the perpendicular-to-structure diffusivity from collapsing to zero and maximises anisotropy at small values (0.001); larger values (0.01--0.1) add isotropic regularisation. Default: 0.001.'), 'dt': FieldInfo(annotation=float, required=False, default=0.1, description='Time step per diffusion iteration. Must satisfy the 2D forward-Euler stability bound (dt <= 0.125). The extent of smoothing is governed by the total diffusion time T = ``num_iter * dt``, so prefer adjusting ``num_iter`` rather than ``dt`` when tuning effect magnitude. Typical range: 0.05--0.125. Default: 0.1.', metadata=[TuneSpec(low=0.05, high=0.125, step=None, log=False, categories=None, tunable=True)]), 'num_iter': FieldInfo(annotation=int, required=False, default=20, description='Number of diffusion iterations. Each iteration advances the PDE one time step of size ``dt``; the total diffusion extent is proportional to ``num_iter * dt``. Typical range: 5--100; values 15--30 are the practical working range for most plate-scan images. Default: 20.', metadata=[TuneSpec(low=15, high=30, step=None, log=False, categories=None, tunable=True)]), 'rho': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Integration scale for structure tensor smoothing in pixels. Averaging the outer-product tensor over ``rho`` produces a smoother orientation field that follows gently curving structures. Must be >= ``sigma``. ``None`` (default) sets ``rho = sigma`` (single-scale mode). Typical values: 2--3x ``sigma``; use values close to ``sigma`` for tight-turning branching mycelium and larger values for long straight streaks.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'sigma': FieldInfo(annotation=float, required=False, default=1.5, description='Noise scale for Gaussian derivative computation in pixels. Sets the spatial frequency band at which local orientation is estimated. Match to the half-width of structures to enhance: fine hyphae (< 3 px) need sigma 0.5--1.0; thick ridges or streak bands tolerate 2--4. Typical range: 0.5--5.0.', metadata=[TuneSpec(low=0.5, high=5.0, step=None, log=True, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

num_iter: Annotated[int, TuneSpec(15, 30)]

rho: Annotated[float | None, TuneSpec(tunable=False)]

sigma: Annotated[float, TuneSpec(0.5, 5.0, log=True)]

class phenotypic.enhance.SubtractGaussian(*, sigma: Annotated[float, TuneSpec(low=20.0, high=100.0, step=None, log=False, categories=None, tunable=True)] = 50.0, mode: str = 'reflect', cval: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0.0, truncate: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 4.0, preserve_range: bool = True, n_iter: Annotated[int, Ge(ge=1), TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)] = 1)

Bases: BackgroundSubtraction

Remove background from detect_mat by subtracting a Gaussian-blurred estimate.

Estimates a smooth background by blurring the image with a wide Gaussian kernel and subtracts it, removing gradual illumination gradients such as vignetting, agar thickness variation, and scanner shading while retaining sharp colony features. The result is clipped to [0, 1] and improves downstream thresholding and edge detection.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Correcting uneven illumination gradients across the scan bed or plate.

• Flattening background intensity so bright colonies or bright colony features stand out against local background.

• Normalizing batches captured with varying scanner exposure or lamp profiles.

• Plates where illumination varies smoothly and a Gaussian is a reasonable background model.

Consider Also:

• SubtractRollingBall for parabolic background estimation that handles non-Gaussian intensity ramps and sharp gradients more accurately.

• SubtractOpening for OpenCV-accelerated morphological background subtraction in high-throughput pipelines.

• FlattenIllumination for homomorphic filtering that separates illumination from reflectance in the frequency domain.

• ImageInverter before this operation when colonies are dark on bright agar and should be made bright explicitly.

Parameters:

• sigma (Annotated[float, TuneSpec(low=20.0, high=100.0, step=None, log=False, categories=None, tunable=True)]) – Standard deviation of the Gaussian background kernel in pixels. Set larger than the typical colony diameter so that colonies are blurred into the background estimate rather than surviving it; too small a sigma subtracts colony signal along with the background. Typical range: 20–100 for standard plate images. A reasonable starting point is a value somewhat larger than the widest colony present. Default: 50.0.

• mode (str) – Border-handling strategy for the Gaussian convolution. Accepted values: 'reflect' (default), 'constant', 'nearest', 'mirror', 'wrap'.

• cval (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Constant fill value used when mode='constant'. Has no effect for other border modes. Default: 0.0.

• truncate (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Number of standard deviations at which the Gaussian kernel is truncated. Larger values are more accurate but increase compute time. Default: 4.0.

• preserve_range (bool) – Preserve the input pixel value range during Gaussian filtering. Default: True.

• n_iter (Annotated[int, Ge(ge=1), TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)]) – Number of successive background-subtraction passes. Additional passes remove residual gradients left after the first subtraction. Typical range: 1–3. Default: 1.

Returns:

Input image with detect_mat background-subtracted and clipped to [0, 1]. rgb and gray are unchanged.

Return type:

Image

Raises:

ValueError – If n_iter is less than 1.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of background subtraction on plate images. What Enhancement Actually Does for background on illumination correction strategies.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

cval: Annotated[float, TuneSpec(tunable=False)]

mode: str

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'cval': FieldInfo(annotation=float, required=False, default=0.0, description="Constant fill value used when ``mode='constant'``. Has no effect for other border modes. Default: 0.0.", metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'mode': FieldInfo(annotation=str, required=False, default='reflect', description="Border-handling strategy for the Gaussian convolution. Accepted values: ``'reflect'`` (default), ``'constant'``, ``'nearest'``, ``'mirror'``, ``'wrap'``."), 'n_iter': FieldInfo(annotation=int, required=False, default=1, description='Number of successive background-subtraction passes. Additional passes remove residual gradients left after the first subtraction. Typical range: 1--3. Default: 1.', metadata=[Ge(ge=1), TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)]), 'preserve_range': FieldInfo(annotation=bool, required=False, default=True, description='Preserve the input pixel value range during Gaussian filtering. Default: ``True``.'), 'sigma': FieldInfo(annotation=float, required=False, default=50.0, description='Standard deviation of the Gaussian background kernel in pixels. Set larger than the typical colony diameter so that colonies are blurred into the background estimate rather than surviving it; too small a sigma subtracts colony signal along with the background. Typical range: 20--100 for standard plate images. A reasonable starting point is a value somewhat larger than the widest colony present. Default: 50.0.', metadata=[TuneSpec(low=20.0, high=100.0, step=None, log=False, categories=None, tunable=True)]), 'truncate': FieldInfo(annotation=float, required=False, default=4.0, description='Number of standard deviations at which the Gaussian kernel is truncated. Larger values are more accurate but increase compute time. Default: 4.0.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

n_iter: Annotated[int, TuneSpec(1, 3)]

preserve_range: bool

sigma: Annotated[float, TuneSpec(20.0, 100.0)]

truncate: Annotated[float, TuneSpec(tunable=False)]

class phenotypic.enhance.SubtractOpening(*, shape: Literal['square', 'diamond', 'disk'] = 'disk', width: Annotated[int, TuneSpec(low=31, high=101, step=2, log=False, categories=None, tunable=True)] = 51, n_iter: Annotated[int, TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)] = 1)

Bases: BackgroundSubtraction, FootprintMixin

Subtract background from detect_mat via OpenCV-accelerated morphological opening.

Computes the white top-hat transform (original minus morphological opening) using OpenCV’s C++/SIMD backend, isolating bright foreground structures smaller than the structuring element while discarding slow-varying background intensity. Significantly faster than scikit-image equivalents for high-throughput workflows.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Fast background subtraction for high-throughput plate screening or parameter sweeps.

• Removing uneven illumination gradients and agar shading before colony detection.

• Large-batch pipelines where speed is a priority and a flat structuring element is acceptable.

• Drop-in acceleration when SubtractRollingBall is the accuracy reference but runtime is the constraint.

Consider Also:

• SubtractRollingBall for parabolic background estimation that handles gradual, non-uniform intensity ramps more accurately.

• SubtractGaussian for Gaussian-based subtraction with continuous control over the background scale.

• WhiteTophatEnhance when you want to retain only the extracted small bright structures rather than a corrected image.

Parameters:

• shape (Literal['square', 'diamond', 'disk']) – Structuring element geometry. Accepted values: 'disk' (default) for isotropic removal suited to round colonies; 'square' for fastest computation; 'diamond' as a compromise between the two.

• width (Annotated[int, TuneSpec(low=31, high=101, step=2, log=False, categories=None, tunable=True)]) – Diameter of the structuring element in pixels. Must exceed the largest colony diameter to avoid including colony pixels in the background estimate. Typical range: 31–101. Default: 51.

• n_iter (Annotated[int, TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)]) – Number of morphological opening iterations. Additional iterations intensify background removal at the cost of eroding fine colony structure. Default: 1.

Returns:

Input image with detect_mat containing only foreground structures smaller than the structuring element. rgb and gray are unchanged.

Return type:

Image

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of background subtraction on plate images. What Enhancement Actually Does for background on morphological background removal strategies.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'n_iter': FieldInfo(annotation=int, required=False, default=1, description='Number of morphological opening iterations. Additional iterations intensify background removal at the cost of eroding fine colony structure. Default: 1.', metadata=[TuneSpec(low=1, high=3, step=None, log=False, categories=None, tunable=True)]), 'shape': FieldInfo(annotation=Literal['square', 'diamond', 'disk'], required=False, default='disk', description="Structuring element geometry. Accepted values: ``'disk'`` (default) for isotropic removal suited to round colonies; ``'square'`` for fastest computation; ``'diamond'`` as a compromise between the two."), 'width': FieldInfo(annotation=int, required=False, default=51, description='Diameter of the structuring element in pixels. Must exceed the largest colony diameter to avoid including colony pixels in the background estimate. Typical range: 31--101. Default: 51.', metadata=[TuneSpec(low=31, high=101, step=2, log=False, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

n_iter: Annotated[int, TuneSpec(1, 3)]

shape: Literal['square', 'diamond', 'disk']

width: Annotated[int, TuneSpec(31, 101, step=2)]

class phenotypic.enhance.SubtractRollingBall(*, radius: Annotated[int, TuneSpec(low=50, high=200, step=None, log=True, categories=None, tunable=True)] = 100, kernel: WithJsonSchema(json_schema={'type': 'array', 'items': {}}, mode=None)] | None = None, nansafe: bool = False)

Bases: BackgroundSubtraction

Remove background from detect_mat with ImageJ-style rolling-ball subtraction.

Models the background as the surface traced by rolling a parabolic ball under the image intensity landscape, then subtracts it. Removes slow illumination gradients and agar shading while preserving colony structures, and handles non-Gaussian intensity ramps better than Gaussian-based subtraction.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Scanner vignetting, lid glare, or agar thickness variations that produce non-Gaussian illumination gradients.

• Flattening backgrounds so bright colonies or bright colony features stand out against local background.

• Images where Gaussian subtraction leaves residual background near plate edges or bright corners.

Consider Also:

• SubtractGaussian for Gaussian-based subtraction with continuous sigma control when the background gradient is smooth and Gaussian-like.

• SubtractOpening for OpenCV-accelerated morphological background removal in high-throughput pipelines.

• WhiteTophatEnhance for isolating small bright structures rather than producing a corrected background-free image.

• ImageInverter before this operation when colonies are dark on bright agar and should be made bright explicitly.

Parameters:

• radius (Annotated[int, TuneSpec(low=50, high=200, step=None, log=True, categories=None, tunable=True)]) – Rolling-ball radius in pixels. Must exceed the largest colony diameter so that colony pixels do not contribute to the background estimate. Typical range: 50–200. A reasonable starting point is a value larger than the widest colony on the plate. Default: 100.

• kernel (Annotated[ndarray, BeforeValidator(func=~phenotypic.sdk_.typing_._coerce_to_ndarray, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~phenotypic.sdk_.typing_._ndarray_to_list, return_type=list, when_used=always), WithJsonSchema(json_schema={'type': 'array', 'items': {}}, mode=None)] | None) – Optional custom ball or paraboloid array overriding the default parabolic shape. When provided, radius is ignored. Default: None.

• nansafe (bool) – Treat NaN-valued pixels as missing data during background estimation, preventing NaN propagation in masked or padded images. Default: False.

Returns:

Input image with detect_mat background-subtracted. rgb and gray are unchanged.

Return type:

Image

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of background subtraction on plate images. What Enhancement Actually Does for background on rolling-ball and other illumination correction strategies.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

kernel: NdArrayField | None

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'kernel': FieldInfo(annotation=Union[Annotated[ndarray, BeforeValidator, PlainSerializer, WithJsonSchema], NoneType], required=False, default=None, description='Optional custom ball or paraboloid array overriding the default parabolic shape. When provided, ``radius`` is ignored.'), 'nansafe': FieldInfo(annotation=bool, required=False, default=False, description='Treat NaN-valued pixels as missing data during background estimation, preventing NaN propagation in masked or padded images. Default: ``False``.'), 'radius': FieldInfo(annotation=int, required=False, default=100, description='Rolling-ball radius in pixels. Must exceed the largest colony diameter so that colony pixels do not contribute to the background estimate. Typical range: 50--200. A reasonable starting point is a value larger than the widest colony on the plate. Default: 100.', metadata=[TuneSpec(low=50, high=200, step=None, log=True, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

nansafe: bool

radius: Annotated[int, TuneSpec(50, 200, log=True)]

class phenotypic.enhance.SubtractWhiteTophat(*, shape: str = 'diamond', width: Annotated[int | None, TuneSpec(low=3, high=15, step=2, log=False, categories=None, tunable=True)] = None)

Bases: MorphologicalFiltering

Suppress small bright artifacts in detect_mat by subtracting the white top-hat.

Computes the white top-hat (original minus morphological opening) and subtracts it from the image, removing small bright blobs such as dust specks, glare highlights, and condensation artifacts while preserving larger colony structures intact.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Removing small bright artifacts that could be mistaken for tiny colonies during thresholding.

• Reducing glare highlights on shiny agar plates before colony detection.

• Cleaning up dust and condensation artifacts that confuse downstream segmentation.

Consider Also:

• WhiteTophatEnhance when the goal is to isolate small bright structures rather than suppress them.

• GrayOpening for morphological smoothing that removes small bright features without explicit subtraction.

• RankMedianEnhancer for impulsive noise removal via median filtering when artifacts are single-pixel in scale.

Parameters:

• shape (str) – Footprint geometry for the structuring element. Accepted values: 'diamond' (default) and 'disk' provide isotropic behavior suited to round artifacts; 'square' can align with sensor grid patterns.

• width (Annotated[int | None, TuneSpec(low=3, high=15, step=2, log=False, categories=None, tunable=True)]) – Maximum bright-artifact size in pixels targeted for removal. Set smaller than the smallest genuine colony diameter to preserve colonies. None (default) auto-derives a small value as approximately 0.4 % of the shorter image dimension.

Returns:

Input image with detect_mat artifact-suppressed by subtracting the white top-hat. rgb and gray are unchanged.

Return type:

Image

Raises:

ValueError – If an unsupported footprint shape is provided.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of artifact removal on plate images. What Enhancement Actually Does for background on top-hat transforms and artifact suppression strategies.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'shape': FieldInfo(annotation=str, required=False, default='diamond', description='Footprint geometry for the structuring element. Accepted'), 'width': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Maximum bright-artifact size in pixels targeted for removal. Set smaller than the smallest genuine colony diameter to preserve colonies. ``None`` (default) auto-derives a small value as approximately 0.4 % of the shorter image dimension.', metadata=[TuneSpec(low=3, high=15, step=2, log=False, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

shape: str

width: Annotated[int | None, TuneSpec(3, 15, step=2)]

class phenotypic.enhance.VisuShrinkEnhancer(*, use_gat: bool = False, gat_gain: Annotated[float, Gt(gt=0)] = 1.0, gat_mu: Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)] = 0.0, gat_read_sigma: Annotated[float, Ge(ge=0)] = 0.0, gat_scale_factor: Annotated[float | None, Gt(gt=0)] = None, sigma: float | None = None, wavelet: str = 'db2', mode: Literal['soft', 'hard'] = 'soft', wavelet_levels: Annotated[int | None, TuneSpec(low=2, high=6, step=None, log=False, categories=None, tunable=True)] = None, clip: bool = True, rescale_sigma: bool = True)

Bases: _GATSupportMixin, ImageDenoiser

Denoise detect_mat with universal VisuShrink wavelet thresholding.

Decomposes the image into wavelet subbands and zeros all coefficients below the universal threshold T = sigma * sqrt(2 * log(N)), which is near-minimax optimal for Gaussian white noise. The universal threshold with the auto-estimated sigma is conservative and can over-smooth; the skimage gallery recommends supplying a manual sigma below the auto-estimate (e.g. half) for better visual quality.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Flatbed scanner banding and CCD read-noise removal before detection.

• High-ISO camera plate images where colony boundaries must remain sharp after denoising.

• Agar granularity and condensation speckle suppression before edge detection or thresholding.

• Batch pipelines where a single universal threshold is preferred over per-subband tuning.

Consider Also:

• BayesShrinkEnhancer for adaptive per-subband thresholding that preserves more colony texture detail at variable noise levels.

• EnhanceBlockMatch for state-of-the-art structured noise removal at higher computational cost.

• LocalEdgeDenoise for edge-preserving spatial smoothing without wavelet decomposition.

Parameters:

• sigma (float | None) – Noise standard deviation on the [0, 1] intensity scale. Controls the universal threshold T = sigma * sqrt(2 * log(N)). None (default) auto-estimates via MAD of finest-scale wavelet detail coefficients; the universal threshold with this estimate is conservative and often over-smooths — the skimage gallery recommends a manual sigma below the auto-estimate (e.g. half) for better visual quality. Typical range: 0.01–0.05 for standard scanner/camera noise. Has no effect when use_gat=True (the threshold is set using the stabilized-domain value 1.0 internally).

• wavelet (str) – Wavelet family name (PyWavelets string). Use only orthogonal families: 'db2' (default, compact support, good edge localisation), 'db4' (more vanishing moments, suppresses smooth background gradients better), 'sym4' or 'sym6' (near-symmetric, reduced Gibbs ringing). Biorthogonal wavelets produce coloured noise in subbands and are not recommended.

• mode (Literal['soft', 'hard']) – Thresholding mode. 'soft' (default) subtracts the threshold from surviving coefficients, producing continuous output without ringing; recommended for Gaussian noise removal before detection. 'hard' preserves coefficient amplitudes above the threshold exactly, retaining sharper edges at the cost of Gibbs-like artefacts at the threshold boundary.

• wavelet_levels (Annotated[int | None, TuneSpec(low=2, high=6, step=None, log=False, categories=None, tunable=True)]) – Number of decomposition levels. None (default) uses the library heuristic (max levels minus 3). Higher values denoise at larger spatial scales, risking removal of genuine low-contrast colony signal; lower values leave coarse banding intact. Valid range: 1 to floor(log2(min_image_dimension)).

• clip (bool) – Clip output to [0, 1]. Default: True. Soft thresholding on float inputs can produce slightly negative values near dark edges; clipping eliminates these. Automatically deferred to False when use_gat=True.

• rescale_sigma (bool) – Allow skimage to rescale the user-supplied sigma proportionally when it converts integer-dtype inputs to float internally. Default: True. Has no observable effect on the float32 detect_mat used in this project. Automatically forced to False when use_gat=True.

• parameters (# GAT)

• use_gat (bool) – Wrap denoising in the Generalized Anscombe Transform to handle Poisson-Gaussian noise (e.g., low-light fluorescence or high-ISO DSLR images of colonies). Default: False.

• gat_gain (Annotated[float, Gt(gt=0)]) – Camera gain in electrons per ADU. Scales the Poisson noise component in the GAT model. Typical range 0.1–10.0 (consumer DSLR ~0.5–3.0, scientific CCD ~1.0–10.0). Leave at 1.0 for normalized images without calibrated gain. Default: 1.0.

• gat_mu (Annotated[float, TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]) – Read-noise mean (baseline DC offset). Set to 0.0 if dark-frame subtraction has been applied. Default: 0.0.

• gat_read_sigma (Annotated[float, Ge(ge=0)]) – Standard deviation of additive Gaussian read noise. 0.0 (default) assumes pure Poisson noise. For scientific cameras with measurable read noise, obtain from spec sheet in e- RMS and convert: read_sigma_norm = read_sigma_e / (gain * max_counts).

• gat_scale_factor (Annotated[float | None, Gt(gt=0)]) – Multiplier converting normalized [0, 1] data to photon counts before the GAT forward pass. None (default) auto-detects from image bit depth (8-bit → 255, 16-bit → 65535). Override when the effective bit depth differs from metadata (e.g., 14-bit sensor stored as 16-bit padded: use 16383 not 65535).

Returns:

Input image with detect_mat denoised via universal wavelet thresholding. rgb and gray are unchanged.

Return type:

Image

References

[1] D. L. Donoho and I. M. Johnstone, “Ideal spatial adaptation by wavelet shrinkage,” Biometrika, vol. 81, no. 3, pp. 425–455, Sep. 1994. [2] M. Mäkitalo and A. Foi, “Optimal inversion of the generalized Anscombe transformation for Poisson-Gaussian noise,” IEEE Trans. Image Process., vol. 22, no. 1, pp. 91–103, Jan. 2013.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of denoising pipelines on plate images. How To: Denoise Low-Light Images for wavelet denoising strategies on low-light plate images. What Enhancement Actually Does for background on wavelet thresholding and the VisuShrink threshold derivation.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

clip: bool

gat_gain: float

gat_mu: Annotated[float, TuneSpec(tunable=False)]

gat_read_sigma: float

gat_scale_factor: float | None

mode: Literal['soft', 'hard']

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'clip': FieldInfo(annotation=bool, required=False, default=True, description='Clip output to [0, 1]. Default: ``True``. Soft thresholding on float inputs can produce slightly negative values near dark edges; clipping eliminates these. Automatically deferred to ``False`` when ``use_gat=True``.'), 'gat_gain': FieldInfo(annotation=float, required=False, default=1.0, description='Camera gain in electrons per ADU. Scales the Poisson noise component in the GAT model. Typical range 0.1--10.0 (consumer DSLR ~0.5--3.0, scientific CCD ~1.0--10.0). Leave at 1.0 for normalized images without calibrated gain. Default: 1.0.', metadata=[Gt(gt=0)]), 'gat_mu': FieldInfo(annotation=float, required=False, default=0.0, description='Read-noise mean (baseline DC offset). Set to 0.0 if dark-frame subtraction has been applied. Default: 0.0.', metadata=[TuneSpec(low=None, high=None, step=None, log=False, categories=None, tunable=False)]), 'gat_read_sigma': FieldInfo(annotation=float, required=False, default=0.0, description='Standard deviation of additive Gaussian read noise. ``0.0`` (default) assumes pure Poisson noise. For scientific cameras with measurable read noise, obtain from spec sheet in e- RMS and convert: read_sigma_norm = read_sigma_e / (gain * max_counts).', metadata=[Ge(ge=0)]), 'gat_scale_factor': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Multiplier converting normalized [0, 1] data to photon counts before the GAT forward pass. ``None`` (default) auto-detects from image bit depth (8-bit → 255, 16-bit → 65535). Override when the effective bit depth differs from metadata (e.g., 14-bit sensor stored as 16-bit padded: use 16383 not 65535).', metadata=[Gt(gt=0)]), 'mode': FieldInfo(annotation=Literal['soft', 'hard'], required=False, default='soft', description="Thresholding mode. ``'soft'`` (default) subtracts the threshold from surviving coefficients, producing continuous output without ringing; recommended for Gaussian noise removal before detection. ``'hard'`` preserves coefficient amplitudes above the threshold exactly, retaining sharper edges at the cost of Gibbs-like artefacts at the threshold boundary."), 'rescale_sigma': FieldInfo(annotation=bool, required=False, default=True, description='Allow skimage to rescale the user-supplied sigma proportionally when it converts integer-dtype inputs to float internally. Default: ``True``. Has no observable effect on the float32 ``detect_mat`` used in this project. Automatically forced to ``False`` when ``use_gat=True``. # GAT parameters (active only when use_gat=True)'), 'sigma': FieldInfo(annotation=Union[float, NoneType], required=False, default=None, description='Noise standard deviation on the [0, 1] intensity scale. Controls the universal threshold T = sigma * sqrt(2 * log(N)). ``None`` (default) auto-estimates via MAD of finest-scale wavelet detail coefficients; the universal threshold with this estimate is conservative and often over-smooths — the skimage gallery recommends a manual sigma below the auto-estimate (e.g. half) for better visual quality. Typical range: 0.01--0.05 for standard scanner/camera noise. Has no effect when ``use_gat=True`` (the threshold is set using the stabilized-domain value 1.0 internally).'), 'use_gat': FieldInfo(annotation=bool, required=False, default=False, description='Wrap denoising in the Generalized Anscombe Transform to handle Poisson-Gaussian noise (e.g., low-light fluorescence or high-ISO DSLR images of colonies). Default: ``False``.'), 'wavelet': FieldInfo(annotation=str, required=False, default='db2', description='Wavelet family name (PyWavelets string). Use only orthogonal'), 'wavelet_levels': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Number of decomposition levels. ``None`` (default) uses the library heuristic (max levels minus 3). Higher values denoise at larger spatial scales, risking removal of genuine low-contrast colony signal; lower values leave coarse banding intact. Valid range: 1 to floor(log2(min_image_dimension)).', metadata=[TuneSpec(low=2, high=6, step=None, log=False, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

rescale_sigma: bool

sigma: float | None

use_gat: bool

wavelet: str

wavelet_levels: Annotated[int | None, TuneSpec(2, 6)]

class phenotypic.enhance.WhiteTophatEnhance(*, shape: str = 'disk', width: Annotated[int | None, TuneSpec(low=3, high=15, step=2, log=False, categories=None, tunable=True)] = None)

Bases: MorphologicalFiltering

Isolate small bright structures in detect_mat with the white top-hat transform.

Computes the white top-hat (original minus morphological opening) and retains the result, extracting bright features smaller than the structuring element while suppressing larger background structures. Highlights small bright colonies, inocula, or specks against uneven illumination.

For algorithm details, see What Enhancement Actually Does.

Best For:

• Isolating small bright colonies from larger background structures or broad illumination gradients.

• Highlighting faint small colonies against uneven agar illumination.

• Extracting early-stage inocula or pinpoints for quantification.

• Preprocessing before applying a detector tuned for small colony phenotypes.

Consider Also:

• SubtractWhiteTophat when the goal is to suppress small bright artifacts rather than isolate them.

• SubtractOpening for OpenCV-accelerated white top-hat background subtraction that also preserves the surrounding image context.

• FocusBlobLoG for scale-invariant blob detection that responds across a range of colony sizes.

Parameters:

• shape (str) – Footprint geometry for the structuring element. Accepted values: 'disk' (default) for isotropic extraction that preserves rounded colony shapes; 'diamond' for computational efficiency; 'square' to align with sensor grid artifacts.

• width (Annotated[int | None, TuneSpec(low=3, high=15, step=2, log=False, categories=None, tunable=True)]) – Maximum bright-object size in pixels targeted for extraction. Set slightly larger than the maximum colony diameter you want to isolate. None (default) auto-derives a small value as approximately 0.4 % of the shorter image dimension.

Returns:

Input image with detect_mat replaced by the white top-hat result, containing only the extracted small bright structures. rgb and gray are unchanged.

Return type:

Image

Raises:

ValueError – If an unsupported footprint shape is provided.

See also

Tutorial 3: Enhancing Before Detection for a visual walkthrough of morphological enhancement on plate images. What Enhancement Actually Does for background on top-hat transforms and feature isolation strategies.

classmethod __get_pydantic_json_schema__(core_schema: CoreSchema, handler: GetJsonSchemaHandler, /) → JsonSchemaValue

Hook into generating the model’s JSON schema.

Parameters:

• core_schema (CoreSchema) – A pydantic-core CoreSchema. You can ignore this argument and call the handler with a new CoreSchema, wrap this CoreSchema ({‘type’: ‘nullable’, ‘schema’: current_schema}), or just call the handler with the original schema.

• handler (GetJsonSchemaHandler) – Call into Pydantic’s internal JSON schema generation. This will raise a pydantic.errors.PydanticInvalidForJsonSchema if JSON schema generation fails. Since this gets called by BaseModel.model_json_schema you can override the schema_generator argument to that function to change JSON schema generation globally for a type.

Returns:

A JSON schema, as a Python object.

Return type:

JsonSchemaValue

classmethod __pydantic_init_subclass__(**kwargs: Any) → None

Populate field descriptions from the subclass docstring.

Runs once per concrete subclass after pydantic has built its model. Copies parameter descriptions parsed from the Google-style Args: docstring block onto each field’s description slot so they surface in model_json_schema() — the machine-readable contract used by downstream tooling (e.g. an MCP server).

Parameters:

**kwargs (Any) – Class-keyword arguments forwarded by pydantic.

Return type:

None

classmethod __pydantic_on_complete__() → None

This is called once the class and its fields are fully initialized and ready to be used.

This typically happens when the class is created (just before [__pydantic_init_subclass__()][pydantic.main.BaseModel.__pydantic_init_subclass__] is called on the superclass), except when forward annotations are used that could not immediately be resolved. In that case, it will be called later, when the model is rebuilt automatically or explicitly using [model_rebuild()][pydantic.main.BaseModel.model_rebuild].

Return type:

None

classmethod construct(_fields_set: set[str] | None = None, **values: Any) → Self

Parameters:

• _fields_set (set[str] | None)

• values (Any)

Return type:

Self

classmethod from_json(json_data: str | Path | dict) → BaseOperation

Reconstruct an operation from JSON written by to_json().

Accepts a JSON string, a path to a JSON file, or a pre-parsed envelope dict (same input handling as ImagePipeline.from_json()). Polymorphic: ImageOperation.from_json(path) returns whatever concrete operation the file holds. When called on a narrower subclass, the resolved class must be a subclass of it, else a TypeError is raised.

Parameters:

json_data (str | Path | dict) – A JSON string, path to a JSON file, or envelope dict.

Returns:

The reconstructed operation instance.

Raises:

• AttributeError – If the recorded class cannot be resolved in the phenotypic namespace.

• TypeError – If called on a concrete subclass and the file holds a class that is not a subclass of it.

Return type:

BaseOperation

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.abc_ import ImageOperation
>>> from phenotypic.detect import OtsuDetector
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     OtsuDetector().to_json(p)
...     loaded = ImageOperation.from_json(p)  # polymorphic
>>> type(loaded).__name__
'OtsuDetector'

classmethod from_orm(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod model_construct(_fields_set: set[str] | None = None, **values: Any) → Self

Creates a new instance of the Model class with validated data.

Creates a new model setting __dict__ and __pydantic_fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed.

!!! note

model_construct() generally respects the model_config.extra setting on the provided model. That is, if model_config.extra == ‘allow’, then all extra passed values are added to the model instance’s __dict__ and __pydantic_extra__ fields. If model_config.extra == ‘ignore’ (the default), then all extra passed values are ignored. Because no validation is performed with a call to model_construct(), having model_config.extra == ‘forbid’ does not result in an error if extra values are passed, but they will be ignored.

Parameters:

• _fields_set (set[str] | None) – A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [model_fields_set][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the values argument will be used.

• values (Any) – Trusted or pre-validated data dictionary.

Returns:

A new instance of the Model class with validated data.

Return type:

Self

classmethod model_json_schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}', schema_generator: type[~pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, mode: ~typing.Literal['validation', 'serialization'] = 'validation', *, union_format: ~typing.Literal['any_of', 'primitive_type_array'] = 'any_of') → dict[str, Any]

Generates a JSON schema for a model class.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• union_format (Literal['any_of', 'primitive_type_array']) –

  The format to use when combining schemas from unions together. Can be one of:

  • ’any_of’: Use the [anyOf](https://json-schema.org/understanding-json-schema/reference/combining#anyOf)

  keyword to combine schemas (the default). - ‘primitive_type_array’: Use the [type](https://json-schema.org/understanding-json-schema/reference/type) keyword as an array of strings, containing each type of the combination. If any of the schemas is not a primitive type (string, boolean, null, integer or number) or contains constraints/metadata, falls back to any_of.

• schema_generator (type[GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

Returns:

The JSON schema for the given model class.

Return type:

dict[str, Any]

classmethod model_parametrized_name(params: tuple[type[Any], ...]) → str

Compute the class name for parametrizations of generic classes.

This method can be overridden to achieve a custom naming scheme for generic BaseModels.

Parameters:

params (tuple[type[Any], ...]) – Tuple of types of the class. Given a generic class Model with 2 type variables and a concrete model Model[str, int], the value (str, int) would be passed to params.

Returns:

String representing the new class where params are passed to cls as type variables.

Raises:

TypeError – Raised when trying to generate concrete names for non-generic models.

Return type:

str

classmethod model_rebuild(*, force: bool = False, raise_errors: bool = True, _parent_namespace_depth: int = 2, _types_namespace: MappingNamespace | None = None) → bool | None

Try to rebuild the pydantic-core schema for the model.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

Parameters:

• force (bool) – Whether to force the rebuilding of the model schema, defaults to False.

• raise_errors (bool) – Whether to raise errors, defaults to True.

• _parent_namespace_depth (int) – The depth level of the parent namespace, defaults to 2.

• _types_namespace (MappingNamespace | None) – The types namespace, defaults to None.

Returns:

Returns None if the schema is already “complete” and rebuilding was not required. If rebuilding _was_ required, returns True if rebuilding was successful, otherwise False.

Return type:

bool | None

classmethod model_validate(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, from_attributes: bool | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate a pydantic model instance.

Parameters:

• obj (Any) – The object to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• from_attributes (bool | None) – Whether to extract data from object attributes.

• context (Any | None) – Additional context to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Raises:

ValidationError – If the object could not be validated.

Returns:

The validated model instance.

Return type:

Self

classmethod model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

!!! abstract “Usage Documentation”

[JSON Parsing](../concepts/json.md#json-parsing)

Validate the given JSON data against the Pydantic model.

Parameters:

• json_data (str | bytes | bytearray) – The JSON data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Raises:

ValidationError – If json_data is not a JSON string or the object could not be validated.

Return type:

Self

classmethod model_validate_strings(obj: Any, *, strict: bool | None = None, extra: Literal['allow', 'ignore', 'forbid'] | None = None, context: Any | None = None, by_alias: bool | None = None, by_name: bool | None = None) → Self

Validate the given object with string data against the Pydantic model.

Parameters:

• obj (Any) – The object containing string data to validate.

• strict (bool | None) – Whether to enforce types strictly.

• extra (Literal['allow', 'ignore', 'forbid'] | None) – Whether to ignore, allow, or forbid extra data during model validation. See the [extra configuration value][pydantic.ConfigDict.extra] for details.

• context (Any | None) – Extra variables to pass to the validator.

• by_alias (bool | None) – Whether to use the field’s alias when validating against the provided input data.

• by_name (bool | None) – Whether to use the field’s name when validating against the provided input data.

Returns:

The validated Pydantic model.

Return type:

Self

classmethod parse_file(path: str | Path, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• path (str | Path)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod parse_obj(obj: Any) → Self

Parameters:

obj (Any)

Return type:

Self

classmethod parse_raw(b: str | bytes, *, content_type: str | None = None, encoding: str = 'utf8', proto: DeprecatedParseProtocol | None = None, allow_pickle: bool = False) → Self

Parameters:

• b (str | bytes)

• content_type (str | None)

• encoding (str)

• proto (DeprecatedParseProtocol | None)

• allow_pickle (bool)

Return type:

Self

classmethod schema(by_alias: bool = True, ref_template: str = '#/$defs/{model}') → Dict[str, Any]

Parameters:

• by_alias (bool)

• ref_template (str)

Return type:

Dict[str, Any]

classmethod schema_json(*, by_alias: bool = True, ref_template: str = '#/$defs/{model}', **dumps_kwargs: Any) → str

Parameters:

• by_alias (bool)

• ref_template (str)

• dumps_kwargs (Any)

Return type:

str

classmethod update_forward_refs(**localns: Any) → None

Parameters:

localns (Any)

Return type:

None

classmethod validate(value: Any) → Self

Parameters:

value (Any)

Return type:

Self

__copy__() → Self

Returns a shallow copy of the model.

Return type:

Self

__deepcopy__(memo: dict[int, Any] | None = None) → Self

Returns a deep copy of the model.

Parameters:

memo (dict[int, Any] | None)

Return type:

Self

__del__()

Automatically stop tracemalloc when the object is deleted.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

Return type:

None

__iter__() → Generator[tuple[str, Any], None, None]

So dict(model) works.

Return type:

Generator[tuple[str, Any], None, None]

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any]

Used by devtools (https://python-devtools.helpmanual.io/) to pretty print objects.

Parameters:

• fmt (Callable[[Any], Any])

• kwargs (Any)

Return type:

Generator[Any]

__repr_name__() → str

Name of the instance’s class, used in __repr__.

Return type:

str

__repr_recursion__(object: Any) → str

Returns the string representation of a recursive object.

Parameters:

object (Any)

Return type:

str

__rich_repr__() → RichReprResult

Used by Rich (https://rich.readthedocs.io/en/stable/pretty.html) to pretty print objects.

Return type:

RichReprResult

apply(image, inplace=False)

Applies the operation to an image, either in-place or on a copy.

Parameters:

• image (Image) – The arr image to apply the operation on.

• inplace (bool) – If True, modifies the image in place; otherwise, operates on a copy of the image.

Returns:

The modified image after applying the operation.

Return type:

Image

copy(*, include: AbstractSetIntStr | MappingIntStrAny | None = None, exclude: AbstractSetIntStr | MappingIntStrAny | None = None, update: Dict[str, Any] | None = None, deep: bool = False) → Self

Returns a copy of the model.

!!! warning “Deprecated”

This method is now deprecated; use model_copy instead.

If you need include or exclude, use:

`python {test="skip" lint="skip"} data = self.model_dump(include=include, exclude=exclude, round_trip=True) data = {**data, **(update or {})} copied = self.model_validate(data) `

Parameters:

• include (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to include in the copied model.

• exclude (AbstractSetIntStr | MappingIntStrAny | None) – Optional set or mapping specifying which fields to exclude in the copied model.

• update (Dict[str, Any] | None) – Optional dictionary of field-value pairs to override field values in the copied model.

• deep (bool) – If True, the values of fields that are Pydantic models will be deep-copied.

Returns:

A copy of the model with included, excluded and updated fields as specified.

Return type:

Self

dict(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → Dict[str, Any]

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

Return type:

Dict[str, Any]

json(*, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, by_alias: bool = False, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Callable[[Any], Any] | None = PydanticUndefined, models_as_dict: bool = PydanticUndefined, **dumps_kwargs: Any) → str

Parameters:

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None)

• by_alias (bool)

• exclude_unset (bool)

• exclude_defaults (bool)

• exclude_none (bool)

• encoder (Callable[[Any], Any] | None)

• models_as_dict (bool)

• dumps_kwargs (Any)

Return type:

str

model_copy(*, update: Mapping[str, Any] | None = None, deep: bool = False) → Self

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Mapping[str, Any] | None) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Returns:

New model instance.

Return type:

Self

model_dump(*, mode: Literal['json', 'python'] | str = 'python', include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → dict[str, Any]

!!! abstract “Usage Documentation”

[model_dump](../concepts/serialization.md#python-mode)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

• mode (Literal['json', 'python'] | str) – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to include in the output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – A set of fields to exclude from the output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to use the field’s alias in the dictionary key if defined.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A dictionary representation of the model.

Return type:

dict[str, Any]

model_dump_json(*, indent: int | None = None, ensure_ascii: bool = False, include: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, exclude: set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None = None, context: Any | None = None, by_alias: bool | None = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, exclude_computed_fields: bool = False, round_trip: bool = False, warnings: bool | Literal['none', 'warn', 'error'] = True, fallback: Callable[[Any], Any] | None = None, serialize_as_any: bool = False) → str

!!! abstract “Usage Documentation”

[model_dump_json](../concepts/serialization.md#json-mode)

Generates a JSON representation of the model using Pydantic’s to_json method.

Parameters:

• indent (int | None) – Indentation to use in the JSON output. If None is passed, the output will be compact.

• ensure_ascii (bool) – If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.

• include (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to include in the JSON output.

• exclude (set[int] | set[str] | Mapping[int, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | Mapping[str, set[int] | set[str] | Mapping[int, IncEx | bool] | Mapping[str, IncEx | bool] | bool] | None) – Field(s) to exclude from the JSON output.

• context (Any | None) – Additional context to pass to the serializer.

• by_alias (bool | None) – Whether to serialize using field aliases.

• exclude_unset (bool) – Whether to exclude fields that have not been explicitly set.

• exclude_defaults (bool) – Whether to exclude fields that are set to their default value.

• exclude_none (bool) – Whether to exclude fields that have a value of None.

• exclude_computed_fields (bool) – Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.

• round_trip (bool) – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

• warnings (bool | Literal['none', 'warn', 'error']) – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].

• fallback (Callable[[Any], Any] | None) – A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.

• serialize_as_any (bool) – Whether to serialize fields with duck-typing serialization behavior.

Returns:

A JSON string representation of the model.

Return type:

str

model_post_init(_BaseOperation__context: Any) → None

Initialize logging and memory tracking after model construction.

Replaces the legacy __init__ body: creates the per-class logger and, when that logger is enabled for INFO level or higher, starts tracemalloc so per-operation memory usage can be logged.

Parameters:

• __context – Pydantic post-init context (unused).

• _BaseOperation__context (Any)

Return type:

None

to_json(filepath: str | Path | None = None) → str | None

Serialize this operation to JSON.

Captures the operation as a {"class", "params"} envelope: params is model_dump(mode="json") (every declared field, including nested operations and raw arrays; PrivateAttr state such as loggers and timing is excluded automatically), and class records the concrete class name so from_json() can rebuild the right subclass. This mirrors ImagePipeline.to_json().

Parameters:

filepath (str | Path | None) – Optional path to write the JSON to. When None, the JSON string is returned instead. Accepts a str or Path.

Returns:

The JSON string when filepath is None, otherwise None.

Return type:

str | None

Example

>>> import tempfile
>>> from pathlib import Path
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.sdk_ import CONFIG_SUFFIX_OPERATION, ensure_typed_json_suffix
>>> with tempfile.TemporaryDirectory() as d:
...     p = Path(d) / "op.json"
...     saved = ensure_typed_json_suffix(p, CONFIG_SUFFIX_OPERATION)
...     OtsuDetector(ignore_zeros=True).to_json(p)
...     loaded = OtsuDetector.from_json(saved)
>>> loaded.ignore_zeros
True

widget(image: Image | None = None, show: bool = False) → Widget

Return (and optionally display) the root widget.

Parameters:

• image (Image | None) – Optional image to visualize. If provided, visualization controls will be added to the widget.

• show (bool) – Whether to display the widget immediately. Defaults to False.

Returns:

The root widget.

Return type:

ipywidgets.Widget

Raises:

ImportError – If ipywidgets or IPython are not installed.

model_computed_fields = {}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_extra: dict[str, Any] | None

Get extra fields set during validation.

Returns:

A dictionary of extra fields, or None if config.extra is not set to “allow”.

model_fields = {'shape': FieldInfo(annotation=str, required=False, default='disk', description='Footprint geometry for the structuring element. Accepted'), 'width': FieldInfo(annotation=Union[int, NoneType], required=False, default=None, description='Maximum bright-object size in pixels targeted for extraction. Set slightly larger than the maximum colony diameter you want to isolate. ``None`` (default) auto-derives a small value as approximately 0.4 % of the shorter image dimension.', metadata=[TuneSpec(low=3, high=15, step=2, log=False, categories=None, tunable=True)])}

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance.

Returns:

A set of strings representing the fields that have been set,

i.e. that were not filled from defaults.

shape: str

width: Annotated[int | None, TuneSpec(3, 15, step=2)]