fiftyone.utils.image¶

Image utilities.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

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()