SSIMPipe

SSIMPipe is registered as ssim-pipe and implemented in src/autopipeline/components/modules/ssim_pipe.py.

It is the structural-similarity module for image-edit evaluation. The pipe supports both:

• direct RGB SSIM
• luminance-only SSIM after histogram matching

Class

Overview

Registry Entry

Field	Value
Registry key	ssim-pipe
Class	SSIMPipe
Main mixins	SSIMMixin, MaskProcessor
Return type	float

Constructor

Constructor

SSIMPipe(**kwargs)

Module-specific init kwargs

None.

SSIMPipe does not define custom module-level initialization parameters. It relies on:

• SSIMMixin for the computation wrapper
• MaskProcessor for region masking

Methods

Public Methods

Method	Purpose
calc_RGB_channel_ssim(ref_image, edited_image, mask=None, win_size=7, win_sigma=1.5)	Compute RGB SSIM on full images or masked regions.
_get_L_channel_numpy(image)	Convert an RGB image to the LAB luminance channel.
calc_L_channel_ssim(ref_image, edited_image, mask=None, win_size=7, win_sigma=1.5)	Compute SSIM on histogram-matched luminance only.
__call__(...)	Build the mask and dispatch to the requested metric branch.

Signature

Call Signature

SSIMPipe.__call__(
    ref_image: Image.Image,
    edited_image: Image.Image,
    coords: List[Tuple[int, int, int, int]] = None,
    mask_mode: str = None,
    metric: str = "ssim",
    **kwargs,
)

Input / Output

Runtime Inputs

Argument	Required	Meaning
ref_image	Yes	Reference image.
edited_image	Yes	Edited image.
coords	No	Pixel-space boxes used to define the measured region.
mask_mode	No	inner or outer, typically derived from pipeline scope.
metric	Yes	ssim or L_channel_ssim.

Extra runtime kwargs

Key	Default	Meaning
win_size	7	SSIM Gaussian window size.
win_sigma	1.5	SSIM Gaussian window sigma.

Supported Metrics

Metric	What it measures	Better direction
ssim	RGB structural similarity	higher is better
L_channel_ssim	luminance-only similarity after histogram matching	higher is better

ssim

This branch:

1. converts both RGB images into float32 tensors with shape (1, 3, H, W)
2. optionally builds a boolean mask with MaskProcessor
3. calls SSIMMixin.compute(...)

L_channel_ssim

This branch:

1. converts both images from RGB to LAB
2. extracts the L channel
3. histogram-matches the edited luminance to the reference luminance
4. converts the result into single-channel tensors (1, 1, H, W)
5. reduces a 3-channel mask to one channel if necessary
6. calls SSIMMixin.compute(...)

This branch is especially useful when raw color or exposure shifts should not dominate the score.

Input / Output

Return Value

The pipe returns a single float score.

• 1.0 is a near-perfect match
• lower values indicate stronger structural drift
• SSIMMixin may return -1e8 if the low-level SSIM computation becomes NaN

Config

Minimal Config Examples

RGB SSIM

metric_configs:
  ssim:
    pipe_name: ssim-pipe
    init_config:
    scope: unedit_area
    runtime_params:
      win_size: 11
      win_sigma: 1.5

Luminance-only SSIM

metric_configs:
  L_channel_ssim:
    pipe_name: ssim-pipe
    init_config:
    scope: edit_area
    runtime_params:
      win_size: 11
      win_sigma: 1.5

Failure Mode

Failure Semantics

The module itself has only one explicit hard-failure branch:

• unsupported metric -> ValueError

Most practical failure behavior comes from dependencies:

• invalid masks or bad image conversion fail upstream
• low-level SSIMMixin.compute(...) converts NaN into -1e8

This means the pipe is relatively stable, but the score interpretation depends on upstream preprocessing being correct.

Extension

Extension Notes

• Add a new branch here if you want another SSIM-style metric with the same general input contract.
• Keep mask generation aligned with MaskProcessor so pipeline scope continues to work consistently.
• If you change window defaults or luminance preprocessing, document the new metric interpretation because thresholding can shift significantly.