brails.utils.plot_tools module

This module defines utilities for creating visually-appealing figures.

PlotTools()

A utility class for generating visually-appealing image grids.
class brails.utils.plot_tools.PlotTools

Bases: object

A utility class for generating visually-appealing image grids.

The PlotTools class provides static methods to visualize model predictions alongside images, enabling intuitive and structured displays for both qualitative evaluation and presentation purposes. It is designed to support image sets managed through the ImageSet class and prediction outputs from classification models.

To import the PlotTools class, use:

from brails.utils import PlotTools
static plot_images(imageset, rows=2, cols=3, random_seed=None)

Plot a random subset of images from an image set in a grid layout.

Parameters:

  • imageset (ImageSet) – A BRAILS ImageSet object containing the images to be displayed.

  • rows (int, optional) – Number of rows in the display grid. Defaults to 2.

  • cols (int, optional) – Number of columns in the display grid. Defaults to 3.

  • random_seed (Optional[int], optional) – Seed for reproducible random sampling. Defaults to None.

Returns:

This function only displays the images using matplotlib.

Return type:

None

Raises:

ValueError – If the number of available images is smaller than rows * cols.

Example

>>> google_satellite = importer.get_class('GoogleSatellite')()
>>> images_satellite = google_satellite.get_images(
...     small_inventory,
...     'tmp/satellite/'
... )
>>> PlotTools.plot_images(
...     images_satellite,
...     rows=3,
...     cols=4,
...     random_seed=42
... )
# Output:
# A matplotlib figure is displayed with a 2x3 grid of randomly
# selected images from the ImageSet. Each subplot shows one image
# with its filename as the title.
static show_predictions(images, predictions, attribute_name, num_samples='all', crop_image=True)

Display a set of images along with their corresponding predictions.

This method randomly samples a specified number of images from the provided images object, optionally crops the images, resizes them, and then displays them in a grid with the associated predictions.

Parameters:

  • images (ImageSet) – A custom object that holds image paths and metadata. It should have an attribute images (a list of image objects) and dir_path (a string representing the directory path where images are located).

  • predictions (dict) – A dictionary where the keys are image identifiers (e.g., file names or unique keys) and the values are the predicted labels (e.g., binary or categorical values).

  • attribute_name (str) – The name of the attribute being predicted, which is displayed in the title for each image.

  • num_samples (int or str, optional) – The number of images to display. If set to 'all', all images in the set will be displayed. Defaults to 'all'.

  • crop_image (bool, optional) – If set to True, the images will be cropped (top 1/6 and bottom 1/4 removed). If set to False, the images will be displayed without cropping. Defaults to True.

Returns:

None

This method directly displays the plot of images and their predictions, and does not return any value.

Note

  • The images are resized to fit the grid, adjusting for the maximum image height.

  • Axes are hidden for a cleaner presentation, and the prediction value is displayed as the title for each image.

  • The method handles both cropping and resizing while maintaining the image aspect ratio.

Example

>>> PlotTools.show_predictions(
...     images=my_image_set,
...     predictions=my_predictions,
...     attribute_name="Class",
...     num_samples=5,
...     crop_image=True,
)