image-filter/docs/architecture.md

Image Filter class diagrams

These UML-style Mermaid diagrams describe the implemented classes in src/image_filter. Open this Markdown in a Mermaid-capable viewer, or use the adjacent .mmd source files with Mermaid CLI.

Composite and numerical filters

classDiagram
direction TB
class ImageFilter {
  <<abstract>>
  +Capabilities capabilities
  +apply(image, metadata) FilterResult
  +apply_batch(items) list~FilterResult~
}
class NumericFilter {
  <<abstract>>
  +apply(image, metadata) FilterResult
  #_apply_with_layout(image, metadata, layout) FilterResult
  #_compute(image, layout) ndarray
  #_history_entry(image, output, layout) dict
}
class Pipeline {
  +tuple~ImageFilter~ steps
  +Capabilities capabilities
  +apply(image, metadata) FilterResult
}
class SliceWise {
  +ImageFilter filter
  +int axis
  +apply(image, metadata) FilterResult
  #_compute(image, layout) ndarray
}
ImageFilter <|-- NumericFilter
ImageFilter <|-- Pipeline
NumericFilter <|-- SliceWise
Pipeline "0..*" o-- "1..*" ImageFilter : ordered children
SliceWise "0..*" o-- "1" ImageFilter : adapts
NumericFilter <|-- MeanFilter
NumericFilter <|-- GaussianFilter
NumericFilter <|-- MedianFilter
NumericFilter <|-- SobelFilter
NumericFilter <|-- LaplacianFilter
NumericFilter <|-- LoGFilter
NumericFilter <|-- LawsFilter
NumericFilter <|-- GaborFilter
NumericFilter <|-- CannyFilter
NumericFilter <|-- WaveletFilter

ImageFilter is the public Component, Pipeline the Composite, and the ten concrete numerical filters the Leaves. NumericFilter shares validation and history behavior; it is an internal abstract implementation, not a separate public filtering operation. SliceWise is an adapter that can wrap a Leaf or a Pipeline.

The hollow diamond denotes aggregation: immutable children can be shared between pipelines and remain valid independently of any parent. A Pipeline contains at least one child and executes children in order. Inheritance arrows point toward the base class. Public methods use +; internal methods use #.

Input, output, and capability model

classDiagram
direction LR
class ImageItem {
  +ndarray image
  +Mapping metadata
}
class FilterResult {
  +ndarray image
  +Mapping metadata
}
class SpatialLayout {
  +int dimension
  +tuple spatial_axes
  +tuple singleton_axes
  +int channel_axis
}
class Capabilities {
  +frozenset spatial_dimensions
  +str accepted_dtypes
  +str input_range
  +str output_dtype
  +bool preserves_shape
  +bool supports_channels
}
class ImageFilter {
  <<abstract>>
  +apply(image, metadata) FilterResult
  +apply_batch(items) list~FilterResult~
}
class NumericFilter {
  <<abstract>>
}
ImageFilter <|-- NumericFilter
ImageFilter ..> ImageItem : consumes in batches
ImageFilter ..> FilterResult : returns
ImageFilter ..> Capabilities : declares
NumericFilter ..> SpatialLayout : validates and computes

ImageItem groups an array with metadata for batch execution. FilterResult contains the resulting array and copied metadata. SpatialLayout describes the effective spatial axes, ignoring singleton axes and excluding an explicitly declared channel axis. Capabilities describes supported input dimensions and other contracts. Pipeline derives its capabilities from its children.

Source and presentation order

1. src/image_filter/base.py: Component and common numerical behavior.
2. src/image_filter/filters.py: the ten Leaves.
3. src/image_filter/pipeline.py: Composite and slice adapter.
4. src/image_filter/model.py: domain objects and dimension inference.
5. examples/01_single_filter.py through 05_slicewise_pipeline.py: a shared runner with different component configurations.

Editable sources: components.mmd and domain-model.mmd. Keep their diagrams identical to the embedded blocks here when changing class relationships.