Visualization#

Anomalib provides visualization utilities and callbacks to inspect model predictions, anomaly maps, and ground-truth comparisons.

API Reference#

Visualization module for anomaly detection.

This module provides utilities for visualizing anomaly detection results. The key components include:

  • Base Visualizer class defining the visualization interface

  • ImageVisualizer class for image-based visualization

  • Functions for visualizing anomaly maps and segmentation masks

  • Tools for visualizing ImageItem objects

Example

>>> from anomalib.visualization import ImageVisualizer
>>> # Create visualizer
>>> visualizer = ImageVisualizer()
>>> # Generate visualization
>>> vis_result = visualizer.visualize(image=img, pred_mask=mask)
The module ensures consistent visualization by:
  • Providing standardized visualization interfaces

  • Supporting both classification and segmentation results

  • Handling various input formats

  • Maintaining consistent output formats

Note

All visualization functions preserve the input format and dimensions unless explicitly specified otherwise.

class anomalib.visualization.ImageVisualizer(fields=None, overlay_fields=None, field_size=(256, 256), fields_config=None, overlay_fields_config=None, text_config=None, output_dir=None)#

Bases: Visualizer

Image Visualizer.

This class visualizes images and their corresponding anomaly maps during testing and prediction phases of an anomaly detection model.

Parameters:
  • fields (list[str] | None) – List of fields to visualize. Defaults to ["image", "gt_mask"].

  • overlay_fields (list[tuple[str, list[str]]] | None) – List of tuples specifying fields to overlay. Each tuple contains a base field and list of fields to overlay on it. Defaults to [("image", ["anomaly_map"]), ("image", ["pred_mask"])].

  • field_size (tuple[int, int]) – Size of each field in visualization as (width, height). Defaults to (256, 256).

  • fields_config (dict[str, dict[str, Any]] | None) – Custom configurations for field visualization. Merged with DEFAULT_FIELDS_CONFIG. Defaults to None.

  • overlay_fields_config (dict[str, dict[str, Any]] | None) – Custom configurations for field overlays. Merged with DEFAULT_OVERLAY_FIELDS_CONFIG. Defaults to None.

  • text_config (dict[str, Any] | None) – Configuration for text overlay. Merged with DEFAULT_TEXT_CONFIG. Defaults to None.

  • output_dir (str | Path | None) – Directory to save visualizations. Defaults to None.

Examples

Basic usage with default settings:

>>> visualizer = ImageVisualizer()

Customize fields to visualize:

>>> visualizer = ImageVisualizer(
...     fields=["image", "gt_mask", "anomaly_map"],
...     overlay_fields=[("image", ["anomaly_map"])]
... )

Adjust field size:

>>> visualizer = ImageVisualizer(field_size=(512, 512))

Customize anomaly map visualization:

>>> fields_config = {
...     "anomaly_map": {"colormap": True, "normalize": True}
... }
>>> visualizer = ImageVisualizer(fields_config=fields_config)

Modify overlay appearance:

>>> overlay_config = {
...     "pred_mask": {"alpha": 0.7, "color": (255, 0, 0), "mode": "fill"},
...     "anomaly_map": {"alpha": 0.5, "color": (0, 255, 0), "mode": "contour"}
... }
>>> visualizer = ImageVisualizer(overlay_fields_config=overlay_config)

Customize text overlay:

>>> text_config = {
...     "font": "arial.ttf",
...     "size": 20,
...     "color": "yellow",
...     "background": (0, 0, 0, 200)
... }
>>> visualizer = ImageVisualizer(text_config=text_config)

Specify output directory:

>>> visualizer = ImageVisualizer(output_dir="./output/visualizations")

Advanced configuration combining multiple customizations:

>>> visualizer = ImageVisualizer(
...     fields=["image", "gt_mask", "anomaly_map", "pred_mask"],
...     overlay_fields=[
...         ("image", ["anomaly_map"]),
...         ("image", ["pred_mask"])
...     ],
...     field_size=(384, 384),
...     fields_config={
...         "anomaly_map": {"colormap": True, "normalize": True},
...         "pred_mask": {"color": (0, 0, 255)}
...     },
...     overlay_fields_config={
...         "anomaly_map": {"alpha": 0.6, "mode": "fill"},
...         "pred_mask": {"alpha": 0.7, "mode": "contour"}
...     },
...     text_config={
...         "font": "times.ttf",
...         "size": 24,
...         "color": "white",
...         "background": (0, 0, 0, 180)
...     },
...     output_dir="./custom_visualizations"
... )

Note

  • The fields parameter determines which individual fields are visualized

  • The overlay_fields parameter specifies which fields should be overlaid on others

  • Field configurations in fields_config affect how individual fields are visualized

  • Overlay configurations in overlay_fields_config determine how fields are blended when overlaid

  • Text configurations in text_config control the appearance of text labels on visualizations

  • If output_dir is not specified, visualizations will be saved in a default location

For more details on available options for each configuration, refer to the documentation of the visualize_image_item(), visualize_field(), and related functions.

on_predict_batch_end(trainer, pl_module, outputs, batch, batch_idx, dataloader_idx=0)#

Called when the predict batch ends.

Return type:

None

on_test_batch_end(trainer, pl_module, outputs, batch, batch_idx, dataloader_idx=0)#

Called when the test batch ends.

Return type:

None

visualize(predictions)#

Visualize image predictions.

This method visualizes anomaly detection predictions intelligently: - For single items or single-item batches: returns a single image - For multi-item batches: returns a list of images

Parameters:

predictions (ImageItem | NumpyImageItem | ImageBatch | NumpyImageBatch) – The image prediction(s) to visualize. Can be: - ImageItem: Single torch-based image item - NumpyImageItem: Single numpy-based image item - ImageBatch: Batch of torch-based image items - NumpyImageBatch: Batch of numpy-based image items

Returns:

Image.Image or None - For multi-item batches: list[Image.Image | None]

Return type:

Image | list[Image | None] | None

Examples

Visualize a torch-based image item:

>>> from anomalib.data import ImageItem
>>> import torch
>>> item = ImageItem(
...     image=torch.rand(3, 224, 224),
...     anomaly_map=torch.rand(224, 224),
...     pred_mask=torch.rand(224, 224) > 0.5
... )
>>> visualizer = ImageVisualizer()
>>> result = visualizer.visualize(item)
>>> isinstance(result, Image.Image) or result is None
True

Visualize a numpy-based image item:

>>> from anomalib.data import NumpyImageItem
>>> import numpy as np
>>> item = NumpyImageItem(
...     image=np.random.rand(224, 224, 3),
...     anomaly_map=np.random.rand(224, 224),
...     pred_mask=np.random.rand(224, 224) > 0.5
... )
>>> result = visualizer.visualize(item)
>>> isinstance(result, Image.Image) or result is None
True

Visualize a batch with one image (returns single image, not list):

>>> from anomalib.data import ImageBatch
>>> single_batch = ImageBatch(
...     image=torch.rand(1, 3, 224, 224),
...     anomaly_map=torch.rand(1, 224, 224)
... )
>>> result = visualizer.visualize(single_batch)
>>> isinstance(result, Image.Image) or result is None
True

Visualize a batch with multiple images (returns list):

>>> multi_batch = ImageBatch(
...     image=torch.rand(3, 3, 224, 224),
...     anomaly_map=torch.rand(3, 224, 224)
... )
>>> results = visualizer.visualize(multi_batch)
>>> isinstance(results, list) and len(results) == 3
True

Note

  • The method uses the same configuration (fields, overlays, etc.) as specified during initialization of the ImageVisualizer.

  • If an item cannot be visualized (e.g., missing required fields), the corresponding result will be None.

  • This method now behaves identically to the __call__ method.

class anomalib.visualization.Visualizer#

Bases: Callback

Base class for all visualizers.

This class serves as the foundation for implementing visualization functionality in Anomalib. It inherits from PyTorch Lightning’s Callback class to integrate with the training workflow.

The visualizer is responsible for generating visual representations of model outputs during testing and prediction phases. This includes:

  • Visualizing input images

  • Displaying model predictions

  • Showing ground truth annotations

  • Generating overlays and heatmaps

  • Saving visualization results

Example

>>> from anomalib.visualization import Visualizer
>>> # Create custom visualizer
>>> class CustomVisualizer(Visualizer):
...     def visualize(self, **kwargs):
...         # Custom visualization logic
...         pass

Note

All custom visualizers should:
  • Inherit from this base class

  • Implement the visualize method

  • Handle relevant visualization configurations

  • Maintain consistent output formats

anomalib.visualization.visualize_anomaly_map(anomaly_map, colormap=True, normalize=False)#

Visualize an anomaly map by applying normalization and/or colormap.

This function takes an anomaly map and converts it to a visualization by optionally normalizing the values and applying a colormap. The input can be a PIL Image, PyTorch tensor, or NumPy array.

Parameters:
  • anomaly_map (Image | Tensor | ndarray) – Input anomaly map to visualize. Can be: - PIL Image: Will be converted to grayscale if not already - PyTorch tensor: Will be converted to PIL Image - NumPy array: Will be converted to PIL Image

  • colormap (bool) – Whether to apply a colormap to the anomaly map. When True, converts the image to a colored heatmap visualization. When False, converts to RGB grayscale. Defaults to True.

  • normalize (bool) – Whether to normalize the anomaly map values to [0, 255] range before visualization. When True, linearly scales the values using min-max normalization. Defaults to False.

Returns:

Visualized anomaly map as a PIL Image in RGB mode.

If colormap=True, returns a heatmap visualization. Otherwise returns a grayscale RGB image.

Return type:

Image

Examples

Visualize a PIL Image anomaly map:

>>> from PIL import Image
>>> import numpy as np
>>> # Create sample anomaly map
>>> data = np.random.rand(100, 100).astype(np.float32)
>>> anomaly_map = Image.fromarray(data, mode='F')
>>> # Visualize with normalization and colormap
>>> vis = visualize_anomaly_map(anomaly_map, normalize=True, colormap=True)
>>> vis.mode
'RGB'

Visualize a PyTorch tensor anomaly map:

>>> import torch
>>> # Create random tensor
>>> tensor_map = torch.rand(100, 100)
>>> # Visualize without normalization
>>> vis = visualize_anomaly_map(tensor_map, normalize=False, colormap=True)
>>> isinstance(vis, Image.Image)
True

Visualize a NumPy array anomaly map:

>>> # Create random numpy array
>>> array_map = np.random.rand(100, 100)
>>> # Visualize with normalization
>>> vis = visualize_anomaly_map(array_map, normalize=True, colormap=True)
>>> isinstance(vis, Image.Image)
True

Note

  • Input tensors and arrays are automatically converted to PIL Images

  • The function always returns an RGB mode image

  • When normalize=True, uses min-max normalization to [0, 255] range

  • The colormap used is the default from apply_colormap()

anomalib.visualization.visualize_image_item(item, fields=None, overlay_fields=None, field_size=(256, 256), fields_config={'anomaly_map': {'colormap': True, 'normalize': False}, 'gt_mask': {}, 'image': {}, 'pred_mask': {}}, overlay_fields_config={'gt_mask': {'alpha': 1.0, 'color': (255, 255, 255), 'mode': 'contour'}, 'pred_mask': {'alpha': 1.0, 'color': (255, 0, 0), 'mode': 'contour'}}, text_config={'background': (0, 0, 0, 128), 'color': 'white', 'enable': True, 'font': None, 'size': None})#

Visualize specified fields of an ImageItem or NumpyImageItem with configurable options.

This function creates visualizations for individual fields and overlays of an ImageItem or NumpyImageItem. It supports customization of field visualization, overlay composition, and text annotations.

Parameters:
  • item (ImageItem | NumpyImageItem) – An ImageItem or NumpyImageItem instance containing the data to visualize.

  • fields (list[str] | None) – A list of field names to visualize individually. If None, no individual fields are visualized.

  • overlay_fields (list[tuple[str, list[str]]] | None) – A list of tuples, each containing a base field and a list of fields to overlay on it. If None, no overlays are created.

  • field_size (tuple[int, int]) – A tuple (width, height) specifying the size of each visualized field.

  • fields_config (dict[str, dict[str, Any]]) – A dictionary of field-specific visualization configurations.

  • overlay_fields_config (dict[str, dict[str, Any]]) – A dictionary of overlay-specific configurations.

  • text_config (dict[str, Any]) – A dictionary of text annotation configurations.

Return type:

Image | None

Returns:

A PIL Image containing the visualized fields and overlays, or None if no valid fields to visualize.

Raises:
  • AttributeError – If a specified field doesn’t exist in the item.

  • ValueError – If an invalid configuration is provided.

Examples

Basic usage with ImageItem:

>>> item = ImageItem(
...     image_path="image.jpg",
...     gt_mask=mask,
...     pred_mask=pred,
...     anomaly_map=amap
... )
>>> result = visualize_image_item(
...     item,
...     fields=["image", "gt_mask", "pred_mask", "anomaly_map"]
... )

Basic usage with NumpyImageItem:

>>> import numpy as np
>>> item = NumpyImageItem(
...     image=np.random.rand(256, 256, 3),
...     gt_mask=mask_array,
...     pred_mask=pred_array,
...     anomaly_map=amap_array
... )
>>> result = visualize_image_item(
...     item,
...     fields=["image", "gt_mask", "pred_mask", "anomaly_map"]
... )

Visualizing specific fields:

>>> result = visualize_image_item(item, fields=["image", "anomaly_map"])

Creating an overlay:

>>> result = visualize_image_item(
...     item,
...     fields=["image"],
...     overlay_fields=[("image", ["anomaly_map"])]
... )

Multiple overlays:

>>> result = visualize_image_item(
...     item,
...     overlay_fields=[
...         ("image", ["gt_mask"]),
...         ("image", ["pred_mask"]),
...         ("image", ["anomaly_map"])
...     ]
... )

Customizing field visualization:

>>> result = visualize_image_item(
...     item,
...     fields=["image", "anomaly_map"],
...     fields_config={
...         "anomaly_map": {"colormap": True, "normalize": True}
...     }
... )

Adjusting overlay transparency:

>>> result = visualize_image_item(
...     item,
...     overlay_fields=[("image", ["gt_mask", "pred_mask"])],
...     overlay_fields_config={
...         "gt_mask": {"alpha": 0.3},
...         "pred_mask": {"alpha": 0.7}
...     }
... )

Customizing text annotations:

>>> result = visualize_image_item(
...     item,
...     fields=["image", "gt_mask"],
...     text_config={
...         "font": "arial.ttf",
...         "size": 20,
...         "color": "yellow",
...         "background": (0, 0, 0, 180)
...     }
... )

Disabling text annotations:

>>> result = visualize_image_item(
...     item,
...     fields=["image", "gt_mask"],
...     text_config={"enable": False}
... )

Combining multiple customizations:

>>> result = visualize_image_item(
...     item,
...     fields=["image", "gt_mask", "pred_mask"],
...     overlay_fields=[("image", ["anomaly_map"])],
...     field_size=(384, 384),
...     fields_config={
...         "anomaly_map": {"colormap": True, "normalize": True},
...     },
...     overlay_fields_config={
...         "anomaly_map": {"colormap": True},
...     },
...     text_config={
...         "font": "times.ttf",
...         "size": 24,
...         "color": "white",
...         "background": (0, 0, 0, 200)
...     }
... )

Handling missing fields gracefully:

>>> item_no_pred = ImageItem(
...     image_path="image.jpg",
...     gt_mask=mask,
...     anomaly_map=amap
... )
>>> result = visualize_image_item(
...     item_no_pred,
...     fields=["image", "gt_mask", "pred_mask", "anomaly_map"]
... )
# This will visualize all available fields, skipping 'pred_mask'

Custom ordering of fields and overlays:

>>> result = visualize_image_item(
...     item,
...     fields=["anomaly_map", "image", "gt_mask"],
...     overlay_fields=[
...         ("image", ["pred_mask"]),
...         ("image", ["gt_mask", "anomaly_map"]),
...     ]
... )
# This will maintain the specified order in the output

Different masking strategies:

  1. Binary mask visualization:

>>> result = visualize_image_item(
...     item,
...     fields=["gt_mask", "pred_mask"],
...     fields_config={
...         "gt_mask": {"mode": "binary"},
...         "pred_mask": {"mode": "binary"}
...     }
... )
  1. Contour mask visualization:

>>> result = visualize_image_item(
...     item,
...     fields=["gt_mask", "pred_mask"],
...     fields_config={
...         "gt_mask": {"mode": "contour", "color": (0, 255, 0)},
...         "pred_mask": {"mode": "contour", "color": (255, 0, 0)}
...     }
... )
  1. Filled mask visualization:

>>> result = visualize_image_item(
...     item,
...     fields=["gt_mask", "pred_mask"],
...     fields_config={
...         "gt_mask": {"mode": "fill", "color": (0, 255, 0), "alpha": 0.5},
...         "pred_mask": {"mode": "fill", "color": (255, 0, 0), "alpha": 0.5}
...     }
... )
  1. Mixed masking strategies:

>>> result = visualize_image_item(
...     item,
...     fields=["image"],
...     overlay_fields=[("image", ["gt_mask", "pred_mask"])],
...     overlay_fields_config={
...         "gt_mask": {"mode": "contour", "color": (0, 255, 0), "alpha": 0.7},
...         "pred_mask": {"mode": "fill", "color": (255, 0, 0), "alpha": 0.3}
...     }
... )
  1. Combining masking strategies with anomaly map:

>>> result = visualize_image_item(
...     item,
...     fields=["image", "anomaly_map"],
...     overlay_fields=[("image", ["gt_mask", "pred_mask"])],
...     fields_config={
...         "anomaly_map": {"colormap": True, "normalize": True}
...     },
...     overlay_fields_config={
...         "gt_mask": {"mode": "contour", "color": (0, 255, 0), "alpha": 0.7},
...         "pred_mask": {"mode": "fill", "color": (255, 0, 0), "alpha": 0.3}
...     }
... )

Note

  • The function preserves the order of fields as specified in the input.

  • If a field is not available in the item, it will be skipped without raising an error.

  • The function uses default configurations if not provided, which can be overridden by passing custom configurations.

  • For ImageItem, the image is loaded from image_path.

  • For NumpyImageItem, the image is converted from the numpy array.

  • For mask visualization, the mode parameter in fields_config or overlay_fields_config determines how the mask is displayed:

    • 'binary': Shows the mask as a black and white image

    • 'contour': Displays only the contours of the mask

    • 'fill': Fills the mask area with a specified color and transparency

anomalib.visualization.visualize_mask(mask, *, mode='binary', alpha=0.5, color=(255, 0, 0), background_color=(0, 0, 0, 0))#

Visualize a mask with different modes.

This function takes a binary mask and visualizes it in different styles based on the specified mode.

Parameters:
  • mask (Image | Tensor | ndarray) – Input mask to visualize. Can be a PIL Image, PyTorch tensor, or NumPy array. If tensor or array, should be 2D with values in [0, 1] or [0, 255].

  • mode (Literal['contour', 'fill', 'binary', 'L', '1']) –

    Visualization mode:

    • "contour": Draw contours around masked regions

    • "fill": Fill masked regions with semi-transparent color

    • "binary": Return original binary mask

    • "L": Return original grayscale mask

    • "1": Return original binary mask

  • alpha (float) – Alpha value for blending in "fill" mode. Should be between 0.0 and 1.0. Defaults to 0.5.

  • color (tuple[int, int, int]) – RGB color to apply to mask. Each value should be 0-255. Defaults to (255, 0, 0) (red).

  • background_color (tuple[int, int, int, int]) – RGBA background color. Each value should be 0-255. Defaults to (0, 0, 0, 0) (transparent).

Returns:

Visualized mask as a PIL Image. The output mode depends on the visualization mode:

  • "contour" and "fill": Returns RGBA image

  • "binary", "L", "1": Returns grayscale image

Return type:

Image

Raises:
  • TypeError – If mask is not a PIL Image, PyTorch tensor, or NumPy array.

  • ValueError – If mode is not one of the allowed values.

Examples

Create a random binary mask:

>>> import numpy as np
>>> from PIL import Image
>>> mask_array = np.random.randint(0, 2, size=(100, 100), dtype=np.uint8) * 255
>>> mask_image = Image.fromarray(mask_array, mode='L')

Visualize mask contours in red:

>>> contour_vis = visualize_mask(
...     mask_image,
...     mode="contour",
...     color=(255, 0, 0)
... )
>>> isinstance(contour_vis, Image.Image)
True

Fill mask regions with semi-transparent green:

>>> fill_vis = visualize_mask(
...     mask_image,
...     mode="fill",
...     color=(0, 255, 0),
...     alpha=0.3
... )
>>> isinstance(fill_vis, Image.Image)
True

Return original binary mask:

>>> binary_vis = visualize_mask(mask_image, mode="binary")
>>> binary_vis.mode
'L'

Use NumPy array input:

>>> mask_array = np.random.randint(0, 2, size=(100, 100), dtype=np.uint8) * 255
>>> vis = visualize_mask(mask_array, mode="contour")
>>> isinstance(vis, Image.Image)
True

Note

  • Input tensors and arrays are automatically converted to PIL Images

  • Binary masks are expected to have values of 0 and 255 (or 0 and 1 for tensors)

  • The function preserves the original mask when using "binary", "L" or "1" modes

  • "contour" mode uses edge detection to find mask boundaries

  • "fill" mode creates a semi-transparent overlay using the specified color