fiftyone.utils.patches

Image patch utilities.

Copyright 2017-2025, Voxel51, Inc.

voxel51.com

Classes:

ImagePatchesExtractor(samples[, ...])

Class for iterating over the labeled/unlabeled image patches in a collection.

Functions:

parse_patches(doc, patches_field[, ...])	Parses the patches from the given document.
extract_patch(img, detection[, ...])	Extracts the patch from the image.

class fiftyone.utils.patches.ImagePatchesExtractor(samples, patches_field=None, include_labels=False, force_rgb=False, force_square=False, alpha=None)

Bases: object

Class for iterating over the labeled/unlabeled image patches in a collection.

By default, this class emits only the image patches, but you can set include_labels to True to emit (img_patch, label) tuples.

Parameters:

• samples – a fiftyone.core.collections.SampleCollection

• patches_field (None) – the name of the field defining the image patches in each sample to extract. Must be of type fiftyone.core.labels.Detection, fiftyone.core.labels.Detections, fiftyone.core.labels.Polyline, or fiftyone.core.labels.Polylines. This can be automatically inferred (only) if samples is a patches view

• include_labels (False) – whether to emit (img_patch, label) tuples rather than just image patches

• force_rgb (False) – whether to force convert the images to RGB

• force_square (False) – whether to minimally manipulate the patch bounding boxes into squares prior to extraction

• alpha (None) – an optional expansion/contraction to apply to the patches before extracting them, in [-1, inf). If provided, the length and width of the box are expanded (or contracted, when alpha < 0) by (100 * alpha)%. For example, set alpha = 0.1 to expand the boxes by 10%, and set alpha = -0.1 to contract the boxes by 10%

fiftyone.utils.patches.parse_patches(doc, patches_field, handle_missing='skip')

Parses the patches from the given document.

Parameters:

• patches_field – the name of the field defining the image patches. Must be of type fiftyone.core.labels.Detection, fiftyone.core.labels.Detections, fiftyone.core.labels.Polyline, or fiftyone.core.labels.Polylines

• handle_missing ("skip") –

  how to handle documents with no patches. Supported values are:

  • ”skip”: skip the document and return None

  • ”image”: use the whole image as a single patch

  • ”error”: raise an error

Returns:

a fiftyone.core.labels.Detections instance, or None

fiftyone.utils.patches.extract_patch(img, detection, force_square=False, alpha=None)

Extracts the patch from the image.

Parameters:

• img – a numpy image array

• detection – a fiftyone.core.labels.Detection defining the patch

• force_square (False) – whether to minimally manipulate the patch bounding box into a square prior to extraction

• alpha (None) – an optional expansion/contraction to apply to the patch before extracting it, in [-1, inf). If provided, the length and width of the box are expanded (or contracted, when alpha < 0) by (100 * alpha)%. For example, set alpha = 0.1 to expand the box by 10%, and set alpha = -0.1 to contract the box by 10%

Returns:

the image patch