fiftyone.utils.image#

Image utilities.

Copyright 2017-2025, Voxel51, Inc.

Functions:

read(path_or_url[, include_alpha, flag])

Reads the image from the given path as a numpy array.

write(img, path)

Writes image to file.

reencode_images(sample_collection[, ext, ...])

Re-encodes the images in the sample collection to the given format.

transform_images(sample_collection[, size, ...])

Transforms the images in the sample collection according to the provided parameters.

reencode_image(input_path, output_path)

Re-encodes the image to the format specified by the given output path.

transform_image(input_path, output_path[, ...])

Transforms the image according to the provided parameters.

fiftyone.utils.image.read(path_or_url, include_alpha=False, flag=None)#

Reads the image from the given path as a numpy array.

Color images are returned as RGB arrays.

Parameters:
  • path – the filepath or URL of the image

  • include_alpha (False) – whether to include the alpha channel of the image, if present, in the returned array

  • flag (None) – an optional OpenCV image format flag to use. If provided, this flag takes precedence over include_alpha

Returns:

a uint8 numpy array containing the image

fiftyone.utils.image.write(img, path)#

Writes image to file.

Parameters:
  • img – a numpy array

  • path – the output path

fiftyone.utils.image.reencode_images(sample_collection, ext='.png', force_reencode=True, media_field='filepath', output_field=None, output_dir=None, rel_dir=None, update_filepaths=True, delete_originals=False, num_workers=None, skip_failures=False, progress=None)#

Re-encodes the images in the sample collection to the given format.

If no output_dir is specified and delete_originals is False, then if a transformation would result in overwriting an existing file with the same filename, the original file is renamed to <name>-original.<ext>.

Note

This method will not update the metadata field of the collection after transforming. You can repopulate the metadata field if needed by calling:

sample_collection.compute_metadata(overwrite=True)
Parameters:
  • sample_collection – a fiftyone.core.collections.SampleCollection

  • ext (".png") – the image format to use (e.g., “.png” or “.jpg”)

  • force_reencode (True) – whether to re-encode images whose extension already matches ext

  • media_field ("filepath") – the input field containing the image paths to transform

  • output_field (None) – an optional field in which to store the paths to the transformed images. By default, media_field is updated in-place

  • output_dir (None) – an optional output directory in which to write the transformed images. If none is provided, the images are updated in-place

  • rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier that is joined with output_dir to generate an output path for each image. This argument allows for populating nested subdirectories in output_dir that match the shape of the input paths

  • update_filepaths (True) – whether to store the output paths on the sample collection

  • delete_originals (False) – whether to delete the original images after re-encoding

  • num_workers (None) – a suggested number of worker processes to use

  • skip_failures (False) – whether to gracefully continue without raising an error if an image cannot be re-encoded

  • progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

fiftyone.utils.image.transform_images(sample_collection, size=None, min_size=None, max_size=None, interpolation=None, ext=None, force_reencode=False, media_field='filepath', output_field=None, output_dir=None, rel_dir=None, update_filepaths=True, delete_originals=False, num_workers=None, skip_failures=False, progress=None)#

Transforms the images in the sample collection according to the provided parameters.

If no output_dir is specified and delete_originals is False, then if a transformation would result in overwriting an existing file with the same filename, the original file is renamed to <name>-original.<ext>.

Note

This method will not update the metadata field of the collection after transforming. You can repopulate the metadata field if needed by calling:

sample_collection.compute_metadata(overwrite=True)
Parameters:
  • sample_collection – a fiftyone.core.collections.SampleCollection

  • size (None) – an optional (width, height) for each image. One dimension can be -1, in which case the aspect ratio is preserved

  • min_size (None) – an optional minimum (width, height) for each image. A dimension can be -1 if no constraint should be applied. The images are resized (aspect-preserving) if necessary to meet this constraint

  • max_size (None) – an optional maximum (width, height) for each image. A dimension can be -1 if no constraint should be applied. The images are resized (aspect-preserving) if necessary to meet this constraint

  • interpolation (None) – an optional interpolation argument for cv2.resize()

  • ext (None) – an optional image format to re-encode the source images into (e.g., “.png” or “.jpg”)

  • force_reencode (False) – whether to re-encode images whose parameters already match the specified values

  • media_field ("filepath") – the input field containing the image paths to transform

  • output_field (None) – an optional field in which to store the paths to the transformed images. By default, media_field is updated in-place

  • output_dir (None) – an optional output directory in which to write the transformed images. If none is provided, the images are updated in-place

  • rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier that is joined with output_dir to generate an output path for each image. This argument allows for populating nested subdirectories in output_dir that match the shape of the input paths

  • update_filepaths (True) – whether to store the output paths on the sample collection

  • delete_originals (False) – whether to delete the original images if any transformation was applied

  • num_workers (None) – a suggested number of worker processes to use

  • skip_failures (False) – whether to gracefully continue without raising an error if an image cannot be transformed

  • progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

fiftyone.utils.image.reencode_image(input_path, output_path)#

Re-encodes the image to the format specified by the given output path.

Parameters:
  • input_path – the path to the input image

  • output_path – the path to write the output image

fiftyone.utils.image.transform_image(input_path, output_path, size=None, min_size=None, max_size=None, interpolation=None)#

Transforms the image according to the provided parameters.

Parameters:
  • input_path – the path to the input image

  • output_path – the path to write the output image

  • size (None) – an optional (width, height) for the image. One dimension can be -1, in which case the aspect ratio is preserved

  • min_size (None) – an optional minimum (width, height) for the image. A dimension can be -1 if no constraint should be applied. The image is resized (aspect-preserving) if necessary to meet this constraint

  • max_size (None) – an optional maximum (width, height) for the image. A dimension can be -1 if no constraint should be applied. The image is resized (aspect-preserving) if necessary to meet this constraint

  • interpolation (None) – an optional interpolation argument for cv2.resize()