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
Visualizerclass defining the visualization interface
ImageVisualizerclass for image-based visualizationFunctions for visualizing anomaly maps and segmentation masks
Tools for visualizing
ImageItemobjects
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:
VisualizerImage 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 withDEFAULT_FIELDS_CONFIG. Defaults toNone.overlay_fields_config (
dict[str,dict[str,Any]] |None) – Custom configurations for field overlays. Merged withDEFAULT_OVERLAY_FIELDS_CONFIG. Defaults toNone.text_config (
dict[str,Any] |None) – Configuration for text overlay. Merged withDEFAULT_TEXT_CONFIG. Defaults toNone.output_dir (
str|Path|None) – Directory to save visualizations. Defaults toNone.
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
fieldsparameter determines which individual fields are visualizedThe
overlay_fieldsparameter specifies which fields should be overlaid on othersField configurations in
fields_configaffect how individual fields are visualizedOverlay configurations in
overlay_fields_configdetermine how fields are blended when overlaidText configurations in
text_configcontrol the appearance of text labels on visualizationsIf
output_diris 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.ImageorNone- 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:
CallbackBase class for all visualizers.
This class serves as the foundation for implementing visualization functionality in Anomalib. It inherits from PyTorch Lightning’s
Callbackclass 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
visualizemethodHandle 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 Imagecolormap (
bool) – Whether to apply a colormap to the anomaly map. WhenTrue, converts the image to a colored heatmap visualization. WhenFalse, converts to RGB grayscale. Defaults toTrue.normalize (
bool) – Whether to normalize the anomaly map values to [0, 255] range before visualization. WhenTrue, linearly scales the values using min-max normalization. Defaults toFalse.
- 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] rangeThe 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
ImageItemorNumpyImageItemwith configurable options.This function creates visualizations for individual fields and overlays of an
ImageItemorNumpyImageItem. It supports customization of field visualization, overlay composition, and text annotations.- Parameters:
item (
ImageItem|NumpyImageItem) – AnImageItemorNumpyImageIteminstance containing the data to visualize.fields (
list[str] |None) – A list of field names to visualize individually. IfNone, 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. IfNone, 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
Imagecontaining the visualized fields and overlays, orNoneif 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:
Binary mask visualization:
>>> result = visualize_image_item( ... item, ... fields=["gt_mask", "pred_mask"], ... fields_config={ ... "gt_mask": {"mode": "binary"}, ... "pred_mask": {"mode": "binary"} ... } ... )
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)} ... } ... )
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} ... } ... )
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} ... } ... )
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 fromimage_path.For
NumpyImageItem, the image is converted from the numpy array.For mask visualization, the
modeparameter infields_configoroverlay_fields_configdetermines 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 to0.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
maskis not a PIL Image, PyTorch tensor, or NumPy array.ValueError – If
modeis 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