phenotypic.abc_.ObjectRefiner#

class phenotypic.abc_.ObjectRefiner[source]#

Bases: ImageOperation, ABC

Abstract base class for post-detection refinement operations that modify object masks and maps.

ObjectRefiner is the foundation for all post-detection cleanup algorithms that refine colony detections through morphological operations, filtering, and merging. Unlike ObjectDetector (which analyzes image data to create initial detections), ObjectRefiner only modifies the object mask and labeled map, leaving preprocessing data untouched.

Quick Decision Guide: ObjectRefiner vs Alternatives

Use ObjectRefiner if: Detector produces mostly correct detections with manageable noise/artifacts (small objects, fragmented regions, holes, low circularity) that can be characterized and filtered.
Use ObjectDetector if: Detector fundamentally fails to detect colonies or produces too much noise to salvage via post-hoc cleanup.
Use ImageEnhancer if: Problem is image quality (blur, contrast, noise) affecting detection; improve input before detection rather than refining output.
ObjectRefiner vs ObjectDetector: Refiners work on existing masks (objmask/objmap), detectors create masks from image data. Refiners are for cleanup, detectors are for initial analysis.
Size filtering: Use for removing dust, noise, agar artifacts (too small) or unrealistic regions (too large). Example: [SmallObjectRemover](src/phenotypic/refine/_small_object_remover.py).
Morphological cleanup: Use for fragmented edges, thin protrusions, internal gaps. Example: [MaskDilation](src/phenotypic/refine/_mask_dilation.py) (uses FootprintMixin).
Hole filling: Use for voids from uneven illumination or pigment patterns within colonies.
Shape filtering: Use for removing elongated artifacts, merged colonies, low-circularity debris.
Merging operations: Use for bridging fragmented colonies or combining nearby regions. Example: [NearestNeighborMerger](src/phenotypic/refine/_nearest_neighbor_merger.py).
When to chain: Combine multiple refiners in ImagePipeline (remove small noise before filling holes, filter shapes before morphological operations) for clearer, divide-and-conquer approach.

What is ObjectRefiner?

ObjectRefiner operates on the principle of non-destructive post-processing: all modifications are applied only to image.objmask (binary mask) and image.objmap (labeled map), while original image components (image.rgb, image.gray, image.detect_mat) remain protected and unchanged. This allows you to experiment with multiple refinement chains without affecting raw or enhanced image data, ensuring reproducibility and enabling comparison of different cleanup strategies.

Key Principle: ObjectRefiner Modifies Only Detection Results

ObjectRefiner operations:

Read image.objmask[:] (binary mask) and image.objmap[:] (labeled map) from prior detection.
Write only image.objmask[:] and image.objmap[:] with refined results.
Protect image.rgb, image.gray, and image.detect_mat via automatic integrity validation (@validate_operation_integrity decorator).

Any attempt to modify protected image components raises OperationIntegrityError when phenotypic.settings.VALIDATE_OPS is true (enabled during development/testing).

Role in the Detection-to-Measurement Pipeline

ObjectRefiner sits after detection but before measurement:

Raw Image (rgb, gray, detect_mat)
      ↓
ImageEnhancer(s) → Improve visibility, reduce noise
      ↓
ObjectDetector → Detect colonies/objects (initial, often noisy)
      ↓
ObjectRefiner(s) → Clean up detections (optional but recommended)
      ↓
MeasureFeatures → Extract colony properties
      ↓
Analysis → Statistical phenotyping, clustering, growth curves

When you call refiner.apply(image), you get back an Image with refined objmask and objmap but identical preprocessing and image data—ready for downstream measurement and analysis.

Why Refinement Matters for Colony Phenotyping

Raw detections from ObjectDetector often contain artifacts:

Spurious small objects: Dust, sensor noise, agar texture, or salt-and-pepper thresholding artifacts create false-positive detections that bias colony counts and statistics.
Fragmented colonies: Uneven lighting, pigment heterogeneity, or aggressive thresholding fragments a single colony into multiple disconnected regions, inflating counts and distorting area measurements.
Merged colonies: In dense plates or when colonies touch, thresholding may merge adjacent colonies into a single detection, losing individuality and requiring post-hoc separation.
Holes in masks: Internal voids within colony masks (from glare or non-uniform pigmentation) create discontinuous shapes that confuse morphological measurements or downstream analysis.
Border artifacts: Colonies touching plate or well boundaries may be incomplete, biasing per-well phenotyping in high-throughput formats.

Refinement operations target these issues with domain-specific strategies: morphological operations (erosion, dilation, opening, closing), shape filtering (circularity, solidity), size thresholding, and boundary enforcement to produce clean, valid detection results.

Differences: ObjectDetector vs ObjectRefiner

ObjectDetector: Analyzes image data (grayscale, RGB, color spaces) and produces initial objmask and objmap. Input: enhanced image. Output: detection results. Typical use: thresholding, edge detection, peak finding, watershed segmentation.
ObjectRefiner: Modifies existing objmask and objmap without analyzing image data. Input: detection results. Output: refined detection results. Typical use: size filtering, morphological cleanup, shape filtering, merging/splitting objects, border removal.

When to Use ObjectRefiner vs Building Better ObjectDetector

Should you refine or improve the detector? Consider:

Use ObjectRefiner if: - The detector produces mostly correct detections but with manageable noise/artifacts - You can characterize the artifacts (small, fragmented, low-circularity, etc.) - Chaining simple refinement operations is clearer than tuning detector parameters - You want to compare cleanup strategies or enable parameter sweeps
Improve ObjectDetector if: - The detector fundamentally fails (misses most colonies, detects at wrong threshold) - Raw detections are too noisy to salvage through simple refinement - The problem is best solved through domain-specific detection logic, not post-hoc cleanup - You have labeled ground truth for detector optimization

Typical Refinement Strategies

Common ObjectRefiner implementations address specific issues:

Size filtering: [SmallObjectRemover](src/phenotypic/refine/_small_object_remover.py) removes objects below/above thresholds. Targets: spurious noise, dust, agar artifacts, oversized regions.
Shape filtering: Remove objects with poor morphology (low circularity, low solidity, high aspect ratio). Targets: elongated artifacts, merged colonies, debris.
Hole filling: Fill interior voids within colony masks for solid shape representation. Targets: voids from uneven illumination, pigment heterogeneity. Improves area measurements.
Morphological operations: Erosion, dilation, opening, closing with [MaskDilation](src/phenotypic/refine/_mask_dilation.py), [MaskErosion](src/phenotypic/refine/_mask_erosion.py), [MaskOpening](src/phenotypic/refine/_mask_opening.py). Targets: fragmented edges, thin protrusions, internal gaps. Uses FootprintMixin for shape control.
Border removal: Remove or exclude objects touching image/well boundaries. Targets: incomplete colonies in arrayed formats.
Merging/splitting: [NearestNeighborMerger](src/phenotypic/refine/_nearest_neighbor_merger.py) combines nearby objects via dilation and relabeling. Targets: fragmented colonies, nearby regions.

Integrity Validation: Protection of Core Data

ObjectRefiner uses the @validate_operation_integrity decorator on the apply() method to guarantee that preprocessing data are never modified:

@validate_operation_integrity('image.rgb', 'image.gray', 'image.detect_mat')
def apply(self, image: Image, inplace: bool = False) -> Image:
    return super().apply(image=image, inplace=inplace)

This decorator:

Calculates cryptographic signatures of image.rgb, image.gray, and image.detect_mat before processing
Calls the parent apply() method to execute your _operate() implementation
Recalculates signatures after operation completes
Raises OperationIntegrityError if any protected component was modified

Note: Integrity validation only runs if phenotypic.settings.VALIDATE_OPS is true (development-time safety; disabled in production for performance).

Implementing a Custom ObjectRefiner

Subclass ObjectRefiner and implement a single method:

from phenotypic.abc_ import ObjectRefiner
from phenotypic import Image
from skimage.morphology import remove_small_objects

class MyCustomRefiner(ObjectRefiner):
    min_size: int = 50  # Annotated class-level field

    def _operate(self, image: Image) -> Image:
        # Modify ONLY objmap; read, process, write back
        # objmask will be auto-updated from objmap via relabel()
        refined_map = remove_small_objects(
            image.objmap[:], min_size=self.min_size
        )
        image.objmap[:] = refined_map
        return image

Morphological Operations with FootprintMixin

For operations requiring morphological structuring elements (dilation, erosion, opening, closing), inherit from FootprintMixin. See [MaskDilation](src/phenotypic/refine/_mask_dilation.py) for example:

from phenotypic.abc_ import ObjectRefiner
from phenotypic.sdk_ import FootprintMixin
from phenotypic import Image
from skimage.morphology import dilation

class MyMorphRefiner(ObjectRefiner, FootprintMixin):
    footprint_shape: str = 'disk'  # Annotated class-level fields
    footprint_width: int = 2

    def _operate(self, image: Image) -> Image:
        # Use _make_footprint from ObjectRefiner or FootprintMixin
        fp = ObjectRefiner._make_footprint(
            self.footprint_shape, self.footprint_width
        )
        dilated = dilation(image.objmask[:], footprint=fp)
        image.objmask[:] = dilated
        # Reconstruct objmap from dilated mask
        from scipy.ndimage import label as ndi_label
        relabeled, _ = ndi_label(dilated)
        image.objmap[:] = relabeled
        return image

Key Rules for Implementation:

_operate() must be an instance method (access parameters via self).
All parameters except image must be declared as annotated class-level fields.
Only modify ``image.objmask[:]`` and ``image.objmap[:]``—all other components are protected. Reading image data is allowed but modifications will trigger integrity errors.
Always use the accessor pattern: image.objmap[:] = new_data (never direct attribute assignment).
Return the modified Image object.

Modifying objmask and objmap

Within your _operate() method, use the accessor interface to read and write detection results:

# Reading detection data
mask = image.objmask[:]          # Binary mask (True = object)
objmap = image.objmap[:]         # Labeled map (0 = background, 1+ = object label)
objects = image.objects          # High-level ObjectCollection interface

# Modifying detection data
image.objmask[:] = refined_mask  # Full replacement of binary mask
image.objmap[:] = refined_map    # Full replacement of labeled map

# Partial updates (boolean indexing)
# Mark certain labels as background (set to 0)
keep_labels = [1, 3, 5]  # Labels to retain
filtered_map = np.where(np.isin(objmap, keep_labels), objmap, 0)
image.objmap[:] = filtered_map

Relationship Between objmask and objmap

objmap (labeled map): Each pixel contains the object label (0 = background, 1+ = object ID). Authoritative source of truth; defines which pixels belong to which colony.
objmask (binary mask): Simple binary version of objmap; True where objmap > 0, False elsewhere. Derived from objmap via image.objmap.relabel().

When you modify objmap, objmask is automatically updated. When you modify objmask directly, call image.objmap.relabel() to ensure consistency (or reconstruct objmap from objmask via connected-component labeling).

The _make_footprint() Static Utility

ObjectRefiner provides a static helper for generating morphological structuring elements (footprints) used in erosion, dilation, and other morphological operations:

@staticmethod
def _make_footprint(shape: Literal["square", "diamond", "disk"], width: int) -> np.ndarray:
    '''Creates a binary morphological shape for image processing.'''

Footprint Shapes and When to Use Each

“disk”: Circular/isotropic shape. Best for preserving rounded colony shapes and applying uniform processing in all directions. Use for: general-purpose morphology (dilation to merge fragments, erosion to remove noise), operations that respect colony roundness.
“square”: Square shape with 8-connectivity. Emphasizes horizontal/vertical edges and aligns with pixel grid. Use for: grid-aligned artifacts, operations aligned with imaging hardware, when processing speed matters (slightly faster than disk).
“diamond”: Diamond-shaped (rotated square) shape with 4-connectivity. Creates a cross-like neighborhood pattern. Use for: specialized cases where diagonal connections should be de-emphasized; less common in practice.

The width parameter controls the neighborhood size (in pixels). Larger radii affect more neighbors and produce broader morphological effects (merge more fragments, remove larger noise, but risk bridging adjacent colonies). Choose width smaller than minimum inter-colony spacing to avoid creating false merges.

Common Morphological Refinement Patterns

Use _make_footprint() with morphological operations from skimage.morphology:

from skimage.morphology import dilation, erosion, closing, opening
from phenotypic.abc_ import ObjectRefiner

disk_fp = ObjectRefiner._make_footprint('disk', width=3)

# Dilation: expand object regions (merge fragmented colonies)
dilated_mask = dilation(binary_mask, footprint=disk_fp)

# Erosion: shrink object regions (remove thin protrusions, small noise)
eroded_mask = erosion(binary_mask, footprint=disk_fp)

# Closing: dilation then erosion (fill small holes)
closed_mask = closing(binary_mask, footprint=disk_fp)

# Opening: erosion then dilation (remove small noise)
opened_mask = opening(binary_mask, footprint=disk_fp)

Chaining Multiple Refinements

Refinement operations are typically chained to address multiple issues in sequence:

from phenotypic import Image, ImagePipeline
from phenotypic.refine import SmallObjectRemover, MaskFill, RemoveLowCircularity

# Build a refinement pipeline
pipeline = ImagePipeline()
pipeline.add(SmallObjectRemover(min_size=100))          # Remove dust/noise
pipeline.add(MaskFill())                                 # Fill holes in colonies
pipeline.add(RemoveLowCircularity(cutoff=0.75))        # Remove elongated artifacts

# Apply to detected image
image = Image.imread('plate.jpg')
from phenotypic.detect import OtsuDetector
detected = OtsuDetector().apply(image)

# Refine
refined = pipeline.operate([detected])[0]
colonies = refined.objects
print(f"After refinement: {len(colonies)} colonies")

Rationale for chaining:

Order matters: Remove small noise before filling holes (no point filling tiny artifacts). Remove low-circularity objects before morphological operations (cleaner starting point).
Divide and conquer: One refiner per issue (size, shape, holes, borders) is clearer than monolithic operations.
No data loss: Original detection and image data are preserved, so intermediate steps can be inspected and validated.
Reproducibility: Chained operations can be serialized to YAML for documentation and reuse.

Methods and Attributes

None at the ObjectRefiner level; subclasses define refinement parameters

as instance attributes

Type:: e.g., min_size, cutoff, width

apply(image, inplace=False)[source]#: Applies the refinement to an image. Returns a modified Image with refined objmask and objmap but unchanged RGB/gray/detect_mat. Handles copy/inplace logic and validates data integrity.

_operate(image, **kwargs)[source]#: Abstract instance method implemented by subclasses. Performs the actual refinement algorithm. Access parameters via self.

_make_footprint(shape, width)#: Static utility that creates a binary morphological shape (disk, square, or diamond) for use in morphological operations.

Notes

Protected components: The @validate_operation_integrity decorator ensures that image.rgb, image.gray, and image.detect_mat cannot be modified. Only image.objmask and image.objmap can be changed.
Immutability by default: apply(image) returns a modified copy by default. Set inplace=True for memory-efficient in-place modification.
Instance _operate() method: The _operate() method is an instance method; access parameters via self.
Field-based parameters: All _operate() parameters except image are declared as annotated class-level fields. _operate() accesses them via self; pydantic handles construction and serialization.
Accessor pattern: Always use image.objmap[:] = new_data to modify object maps. Never use direct attribute assignment.
objmap/objmask consistency: When modifying objmap, call image.objmap.relabel() to ensure objmask is updated. When modifying objmask directly, reconstruct objmap via connected-component labeling.
Boolean indexing for filtering: Use numpy boolean arrays to filter labels: mask = np.isin(objmap, keep_labels); filtered_map = objmap * mask

Examples

Removing small spurious objects below minimum size:

>>> from phenotypic.abc_ import ObjectRefiner
>>> from phenotypic import Image
>>> from skimage.morphology import remove_small_objects
>>> from scipy import ndimage
>>> class SimpleSmallObjectRemover(ObjectRefiner):
...     '''Remove objects smaller than a minimum size threshold.'''
...
...     min_size: int = 50
...
...     def _operate(self, image: Image) -> Image:
...         '''Remove small objects from labeled map.'''
...         # Get current labeled map
...         objmap = image.objmap[:]
...         # Remove small objects (automatically updates objmap)
...         refined = remove_small_objects(objmap, min_size=self.min_size)
...         # Set refined result
...         image.objmap[:] = refined
...         return image
>>> # Usage
>>> from phenotypic.detect import OtsuDetector
>>> image = Image.imread('plate.jpg')
>>> detected = OtsuDetector().apply(image)
>>> # Remove noise below 100 pixels
>>> refiner = SimpleSmallObjectRemover(min_size=100)
>>> cleaned = refiner.apply(detected)
>>> print(f"Before: {detected.objmap[:].max()} objects")
>>> print(f"After: {cleaned.objmap[:].max()} objects")

Removing low-circularity objects (merged colonies, artifacts):

>>> from phenotypic.abc_ import ObjectRefiner
>>> from phenotypic import Image
>>> from skimage.measure import regionprops_table
>>> import pandas as pd
>>> import numpy as np
>>> import math
>>> class CircularityFilter(ObjectRefiner):
...     '''Remove objects with low circularity (merged colonies, artifacts).'''
...
...     min_circularity: float = 0.7
...
...     def _operate(self, image: Image) -> Image:
...         '''Filter objects by circularity using Polsby-Popper metric.'''
...         objmap = image.objmap[:]
...         # Measure shape properties
...         props = regionprops_table(
...             label_image=objmap,
...             properties=['label', 'area', 'perimeter']
...         )
...         df = pd.DataFrame(props)
...         # Calculate circularity (Polsby-Popper: 4*pi*area / perimeter^2)
...         df['circularity'] = (4 * math.pi * df['area']) / (df['perimeter'] ** 2)
...         # Keep only circular objects
...         keep_labels = df[
...             df['circularity'] >= self.min_circularity
...         ]['label'].values
...         # Filter map: keep only selected labels
...         refined_map = np.where(np.isin(objmap, keep_labels), objmap, 0)
...         image.objmap[:] = refined_map
...         return image
>>> # Usage
>>> image = Image.imread('plate.jpg')
>>> from phenotypic.detect import OtsuDetector
>>> detected = OtsuDetector().apply(image)
>>> # Keep only well-formed circular colonies
>>> refiner = CircularityFilter(min_circularity=0.75)
>>> refined = refiner.apply(detected)
>>> print(f"Removed elongated artifacts: {detected.objmap[:].max()} -> {refined.objmap[:].max()}")

Filling holes in colony masks for solid shape representation:

>>> from phenotypic.abc_ import ObjectRefiner
>>> from phenotypic import Image
>>> from scipy.ndimage import binary_fill_holes
>>> class HoleFiller(ObjectRefiner):
...     '''Fill holes within colony masks for solid shape representation.'''
...
...     def _operate(self, image: Image) -> Image:
...         '''Fill holes in binary mask.'''
...         mask = image.objmask[:]
...         # Fill holes (interior voids within objects)
...         filled = binary_fill_holes(mask)
...         # Update mask
...         image.objmask[:] = filled
...         # Reconstruct labeled map from filled mask
...         from scipy import ndimage
...         labeled, _ = ndimage.label(filled)
...         image.objmap[:] = labeled
...         return image
>>> # Usage
>>> image = Image.imread('plate.jpg')
>>> from phenotypic.detect import OtsuDetector
>>> detected = OtsuDetector().apply(image)
>>> # Fill holes from uneven illumination or pigmentation
>>> refiner = HoleFiller()
>>> refined = refiner.apply(detected)
>>> # Result: solid, contiguous colony shapes better for area measurements
>>> print(f"Holes filled; colonies now solid")

Morphological refinement with dilation to merge fragmented colonies:

>>> from phenotypic.abc_ import ObjectRefiner
>>> from phenotypic import Image
>>> from scipy.ndimage import label as ndi_label
>>> from skimage.morphology import dilation
>>> import numpy as np
>>> class FragmentMerger(ObjectRefiner):
...     '''Merge fragmented colonies via morphological dilation and relabeling.'''
...
...     dilation_radius: int = 2
...
...     def _operate(self, image: Image) -> Image:
...         '''Dilate mask and relabel to merge nearby fragments.'''
...         mask = image.objmask[:]
...         # Create disk shape for isotropic dilation
...         fp = ObjectRefiner._make_footprint('disk', self.dilation_radius)
...         # Dilate to bridge fragmented regions
...         dilated = dilation(mask, footprint=fp)
...         # Relabel connected components
...         relabeled, _ = ndi_label(dilated)
...         # Set refined results
...         image.objmask[:] = dilated
...         image.objmap[:] = relabeled
...         return image
>>> # Usage
>>> image = Image.imread('plate.jpg')
>>> from phenotypic.detect import OtsuDetector
>>> detected = OtsuDetector().apply(image)
>>> # Merge fragments from uneven lighting
>>> refiner = FragmentMerger(dilation_radius=3)
>>> merged = refiner.apply(detected)
>>> print(f"Merged fragments: {detected.objmap[:].max()} -> {merged.objmap[:].max()} objects")

Merging nearby objects via nearest-neighbor distance:

>>> from phenotypic.abc_ import ObjectRefiner
>>> from phenotypic import Image
>>> from scipy.ndimage import label as ndi_label, distance_transform_edt
>>> from skimage.morphology import dilation
>>> import numpy as np
>>> class MergeFragmentChains(ObjectRefiner):
...     '''Merge objects within specified distance via distance transform.'''
...
...     merge_distance: int = 5
...
...     def _operate(self, image: Image) -> Image:
...         '''Merge objects closer than merge_distance via dilation of distance map.'''
...         mask = image.objmask[:]
...         # Compute distance transform from object interior
...         dist_map = distance_transform_edt(mask)
...         # Dilate distance map to bridge nearby objects
...         fp = ObjectRefiner._make_footprint('disk', self.merge_distance)
...         dilated_dist = dilation(dist_map > 0, footprint=fp)
...         # Relabel connected components in dilated region
...         relabeled, _ = ndi_label(dilated_dist)
...         # Set refined results
...         image.objmask[:] = dilated_dist
...         image.objmap[:] = relabeled
...         return image
>>> # Usage: merge nearby fragments from partial colonies
>>> from phenotypic.data import load_synth_yeast_plate
>>> from phenotypic.detect import OtsuDetector
>>> image = load_synth_yeast_plate()
>>> detected = OtsuDetector().apply(image)
>>> # Merge fragments within 10-pixel distance
>>> merger = MergeFragmentChains(merge_distance=10)
>>> merged = merger.apply(detected)
>>> print(f"Merged nearby objects: {detected.objmap[:].max()} -> {merged.objmap[:].max()}")

Chaining multiple refinements in a pipeline:

>>> from phenotypic import Image, ImagePipeline
>>> from phenotypic.enhance import GaussianBlur
>>> from phenotypic.detect import OtsuDetector
>>> from phenotypic.refine import (
...     SmallObjectRemover, MaskFill, RemoveLowCircularity
... )
>>> from phenotypic.measure import MeasureColor
>>> # Build complete processing pipeline with enhancement, detection, and refinement
>>> pipeline = ImagePipeline()
>>> # Preprocessing
>>> pipeline.add(GaussianBlur(sigma=1.5))
>>> # Detection
>>> pipeline.add(OtsuDetector())
>>> # Refinement (chain multiple cleanup operations)
>>> pipeline.add(SmallObjectRemover(min_size=100))          # Remove dust
>>> pipeline.add(MaskFill())                                 # Fill internal holes
>>> pipeline.add(RemoveLowCircularity(cutoff=0.75))        # Remove merged/irregular
>>> # Measurement
>>> pipeline.add(MeasureColor())
>>> # Load images and process
>>> image = Image.imread('plate.jpg')
>>> results = pipeline.operate([image])
>>> final = results[0]
>>> # Access final clean detection results
>>> colonies = final.objects
>>> measurements = final.measurements
>>> print(f"Detected and cleaned: {len(colonies)} colonies")
>>> print(f"Color measurements: {measurements.shape}")

Methods

`__init__`	Create a new model by parsing and validating input data from keyword arguments.
`apply`	Applies the operation to an image, either in-place or on a copy.
`construct`
`copy`	Returns a copy of the model.
`dict`
`from_json`	Reconstruct an operation from JSON written by `to_json()`.
`from_orm`
`json`
`model_construct`	Creates a new instance of the Model class with validated data.
`model_copy`	!!! abstract "Usage Documentation"
`model_dump`	!!! abstract "Usage Documentation"
`model_dump_json`	!!! abstract "Usage Documentation"
`model_json_schema`	Generates a JSON schema for a model class.
`model_parametrized_name`	Compute the class name for parametrizations of generic classes.
`model_post_init`	Initialize logging and memory tracking after model construction.
`model_rebuild`	Try to rebuild the pydantic-core schema for the model.
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	!!! abstract "Usage Documentation"
`model_validate_strings`	Validate the given object with string data against the Pydantic model.
`parse_file`
`parse_obj`
`parse_raw`
`schema`
`schema_json`
`to_json`	Serialize this operation to JSON.
`update_forward_refs`
`validate`
`widget`	Return (and optionally display) the root widget.

Attributes

`model_computed_fields`
`model_config`	Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
`model_extra`	Get extra fields set during validation.
`model_fields`
`model_fields_set`	Returns the set of fields that have been explicitly set on this model instance.

__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.

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

__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]

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

__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: GridImage, inplace: bool = False) → GridImage[source]#

apply(image: Image, inplace: bool = 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

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

Parameters:

_fields_set (set[str] | None)
values (Any)

Return type:

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

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]

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

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_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].

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

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

!!! 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]

!!! 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

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.

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

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

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

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

!!! 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

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

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

classmethod update_forward_refs(**localns: Any) → None#

Parameters:: localns (Any)
Return type:: None

classmethod validate(value: Any) → Self#

Parameters:: value (Any)
Return type:: Self

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.

phenotypic.abc_.ObjectRefiner#

This Page