► Keras 3 API documentation / Utilities / Visualization utilities

Visualization utilities

`draw_bounding_boxes` function

keras.visualization.draw_bounding_boxes(
    images,
    bounding_boxes,
    bounding_box_format,
    class_mapping=None,
    color=(128, 128, 128),
    line_thickness=2,
    text_thickness=1,
    font_scale=1.0,
    data_format=None,
)

Draws bounding boxes on images.

This function draws bounding boxes on a batch of images. It supports different bounding box formats and can optionally display class labels and confidences.

Arguments

images: A batch of images as a 4D tensor or NumPy array. Shape should be (batch_size, height, width, channels).
bounding_boxes: A dictionary containing bounding box data. Should have the following keys:
- boxes: A tensor or array of shape (batch_size, num_boxes, 4) containing the bounding box coordinates in the specified format.
- labels: A tensor or array of shape (batch_size, num_boxes) containing the class labels for each bounding box.
- confidences (Optional): A tensor or array of shape (batch_size, num_boxes) containing the confidence scores for each bounding box.
bounding_box_format: A string specifying the format of the bounding boxes. Refer keras-io
class_mapping: A dictionary mapping class IDs (integers) to class labels (strings). Used to display class labels next to the bounding boxes. Defaults to None (no labels displayed).
color: A tuple or list representing the RGB color of the bounding boxes. For example, (255, 0, 0) for red. Defaults to (128, 128, 128).
line_thickness: An integer specifying the thickness of the bounding box lines. Defaults to 2.
text_thickness: An integer specifying the thickness of the text labels. Defaults to 1.
font_scale: A float specifying the scale of the font used for text labels. Defaults to 1.0.
data_format: A string, either "channels_last" or "channels_first", specifying the order of dimensions in the input images. Defaults to the image_data_format value found in your Keras config file at ~/.keras/keras.json. If you never set it, then it will be "channels_last".

Returns

A NumPy array of the annotated images with the bounding boxes drawn. The array will have the same shape as the input images.

Raises

ValueError: If images is not a 4D tensor/array, if bounding_boxes is not a dictionary, or if bounding_boxes does not contain "boxes" and "labels" keys.
TypeError: If bounding_boxes is not a dictionary.
ImportError: If cv2 (OpenCV) is not installed.

[source]

`draw_segmentation_masks` function

keras.visualization.draw_segmentation_masks(
    images,
    segmentation_masks,
    num_classes=None,
    color_mapping=None,
    alpha=0.8,
    blend=True,
    ignore_index=-1,
    data_format=None,
)

Draws segmentation masks on images.

The function overlays segmentation masks on the input images. The masks are blended with the images using the specified alpha value.

Arguments

images: A batch of images as a 4D tensor or NumPy array. Shape should be (batch_size, height, width, channels).
segmentation_masks: A batch of segmentation masks as a 3D or 4D tensor or NumPy array. Shape should be (batch_size, height, width) or (batch_size, height, width, 1). The values represent class indices starting from 1 up to num_classes. Class 0 is reserved for the background and will be ignored if ignore_index is not 0.
num_classes: The number of segmentation classes. If None, it is inferred from the maximum value in segmentation_masks.
color_mapping: A dictionary mapping class indices to RGB colors. If None, a default color palette is generated. The keys should be integers starting from 1 up to num_classes.
alpha: The opacity of the segmentation masks. Must be in the range [0, 1].
blend: Whether to blend the masks with the input image using the alpha value. If False, the masks are drawn directly on the images without blending. Defaults to True.
ignore_index: The class index to ignore. Mask pixels with this value will not be drawn. Defaults to -1.
data_format: Image data format, either "channels_last" or "channels_first". Defaults to the image_data_format value found in your Keras config file at ~/.keras/keras.json. If you never set it, then it will be "channels_last".

Returns

A NumPy array of the images with the segmentation masks overlaid.

Raises

ValueError: If the input images is not a 4D tensor or NumPy array.
TypeError: If the input segmentation_masks is not an integer type.

[source]

`plot_bounding_box_gallery` function

keras.visualization.plot_bounding_box_gallery(
    images,
    bounding_box_format,
    y_true=None,
    y_pred=None,
    value_range=(0, 255),
    true_color=(0, 188, 212),
    pred_color=(255, 235, 59),
    line_thickness=2,
    font_scale=1.0,
    text_thickness=None,
    class_mapping=None,
    ground_truth_mapping=None,
    prediction_mapping=None,
    legend=False,
    legend_handles=None,
    rows=None,
    cols=None,
    data_format=None,
    **kwargs
)

Plots a gallery of images with bounding boxes.

This function can display both ground truth and predicted bounding boxes on a set of images. It supports various bounding box formats and can include class labels and a legend.

Arguments

images: A 4D tensor or NumPy array of images. Shape should be (batch_size, height, width, channels).
bounding_box_format: The format of the bounding boxes. Refer keras-io
y_true: A dictionary containing the ground truth bounding boxes and labels. Should have the same structure as the bounding_boxes argument in keras.visualization.draw_bounding_boxes. Defaults to None.
y_pred: A dictionary containing the predicted bounding boxes and labels. Should have the same structure as y_true. Defaults to None.
value_range: A tuple specifying the value range of the images (e.g., (0, 255) or (0, 1)). Defaults to (0, 255).
true_color: A tuple of three integers representing the RGB color for the ground truth bounding boxes. Defaults to (0, 188, 212).
pred_color: A tuple of three integers representing the RGB color for the predicted bounding boxes. Defaults to (255, 235, 59).
line_thickness: The thickness of the bounding box lines. Defaults to 2.
font_scale: The scale of the font used for labels. Defaults to 1.0.
text_thickness: The thickness of the bounding box text. Defaults to line_thickness.
class_mapping: A dictionary mapping class IDs to class names. Used f or both ground truth and predicted boxes if ground_truth_mapping and prediction_mapping are not provided. Defaults to None.
ground_truth_mapping: A dictionary mapping class IDs to class names specifically for ground truth boxes. Overrides class_mapping for ground truth. Defaults to None.
prediction_mapping: A dictionary mapping class IDs to class names specifically for predicted boxes. Overrides class_mapping for predictions. Defaults to None.
legend: A boolean indicating whether to show a legend. Defaults to False.
legend_handles: A list of matplotlib Patch objects to use for the legend. If this is provided, the legend argument will be ignored. Defaults to None.
rows: The number of rows in the image gallery. Required if the images are not batched. Defaults to None.
cols: The number of columns in the image gallery. Required if the images are not batched. Defaults to None.
data_format: The image data format "channels_last" or "channels_first". Defaults to the Keras backend data format.
kwargs: Additional keyword arguments to be passed to keras.visualization.plot_image_gallery.

Returns

The output of keras.visualization.plot_image_gallery.

Raises

ValueError: If images is not a 4D tensor/array or if both legend a nd legend_handles are specified.
ImportError: if matplotlib is not installed

[source]

`plot_image_gallery` function

keras.visualization.plot_image_gallery(
    images,
    y_true=None,
    y_pred=None,
    label_map=None,
    rows=None,
    cols=None,
    value_range=(0, 255),
    scale=2,
    path=None,
    show=None,
    transparent=True,
    dpi=60,
    legend_handles=None,
    data_format=None,
)

Displays a gallery of images with optional labels and predictions.

Arguments

images: A 4D tensor or NumPy array of images. Shape should be (batch_size, height, width, channels).
y_true: A 1D tensor or NumPy array of true labels (class indices). Defaults to None.
y_pred: A 1D tensor or NumPy array of predicted labels (class indices). Defaults to None.
label_map: A dictionary mapping class indices to class names. Required if y_true or y_pred are provided. Defaults to None.
value_range: A tuple specifying the value range of the images (e.g., (0, 255) or (0, 1)). Defaults to (0, 255).
rows: The number of rows in the gallery. If None, it's calculated based on the number of images and cols. Defaults to None.
cols: The number of columns in the gallery. If None, it's calculated based on the number of images and rows. Defaults to None.
scale: A float controlling the size of the displayed images. The images are scaled by this factor. Defaults to 2.
path: The path to save the generated gallery image. If None, the image is displayed using plt.show(). Defaults to None.
show: Whether to display the image using plt.show(). If True, the image is displayed. If False, the image is not displayed. Ignored if path is not None. Defaults to True if path is None, False otherwise.
transparent: A boolean, whether to save the figure with a transparent background. Defaults to True.
dpi: The DPI (dots per inch) for saving the figure. Defaults to 60.
legend_handles: A list of matplotlib Patch objects to use as legend handles. Defaults to None.
data_format: The image data format "channels_last" or "channels_first". Defaults to the Keras backend data format.

Raises

ValueError: If both path and show are set to non-None values, if images is not a 4D tensor or array, or if y_true or y_pred are provided without a label_map.
ImportError: if matplotlib is not installed.

[source]

`plot_segmentation_mask_gallery` function

keras.visualization.plot_segmentation_mask_gallery(
    images,
    num_classes,
    value_range=(0, 255),
    y_true=None,
    y_pred=None,
    color_mapping=None,
    blend=True,
    alpha=0.8,
    ignore_index=-1,
    data_format=None,
    **kwargs
)

Plots a gallery of images with corresponding segmentation masks.

Arguments

images: A 4D tensor or NumPy array of images. Shape should be (batch_size, height, width, channels).
num_classes: The number of segmentation classes. Class indices should start from 1. Class 0 will be treated as background and ignored if ignore_index is not 0.
value_range: A tuple specifying the value range of the images (e.g., (0, 255) or (0, 1)). Defaults to (0, 255).
y_true: A 3D/4D tensor or NumPy array representing the ground truth segmentation masks. Shape should be (batch_size, height, width) or (batch_size, height, width, 1). Defaults to None.
y_pred: A 3D/4D tensor or NumPy array representing the predicted segmentation masks. Shape should be the same as y_true. Defaults to None.
color_mapping: A dictionary mapping class indices to RGB colors. If None, a default color palette is used. Class indices start from 1. Defaults to None.
blend: Whether to blend the masks with the input image using the alpha value. If False, the masks are drawn directly on the images without blending. Defaults to True.
alpha: The opacity of the segmentation masks (a float between 0 and 1). Defaults to 0.8.
ignore_index: The class index to ignore when drawing masks. Defaults to -1.
data_format: The image data format "channels_last" or "channels_first". Defaults to the Keras backend data format.
kwargs: Additional keyword arguments to be passed to keras.visualization.plot_image_gallery.