<!-- # hard line break macro for HTML -->

# fiftyone.utils.image

Image utilities.

Copyright 2017-2026, Voxel51, Inc.
<br/>
[voxel51.com](https://voxel51.com/)
<br/>
<br/>

**Functions:**

| [`read`](#fiftyone.utils.image.read)(path_or_url[, include_alpha, flag])                     | Reads the image from the given path as a numpy array.                                |
|----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| [`write`](#fiftyone.utils.image.write)(img, path)                                            | Writes image to file.                                                                |
| [`reencode_images`](#fiftyone.utils.image.reencode_images)(sample_collection[, ext, ...])    | Re-encodes the images in the sample collection to the given format.                  |
| [`transform_images`](#fiftyone.utils.image.transform_images)(sample_collection[, size, ...]) | Transforms the images in the sample collection according to the provided parameters. |
| [`reencode_image`](#fiftyone.utils.image.reencode_image)(input_path, output_path)            | Re-encodes the image to the format specified by the given output path.               |
| [`transform_image`](#fiftyone.utils.image.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:

```default
sample_collection.compute_metadata(overwrite=True)
```

* **Parameters:**
  * **sample_collection** – a
    [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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:

```default
sample_collection.compute_metadata(overwrite=True)
```

* **Parameters:**
  * **sample_collection** – a
    [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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()`