# fiftyone.utils.patches Image patch utilities. Copyright 2017-2026, Voxel51, Inc.
[voxel51.com](https://voxel51.com/)

**Classes:** | [`ImagePatchesExtractor`](#fiftyone.utils.patches.ImagePatchesExtractor)(samples[, ...]) | Class for iterating over the labeled/unlabeled image patches in a collection. | |--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------| **Functions:** | [`parse_patches`](#fiftyone.utils.patches.parse_patches)(doc, patches_field[, ...]) | Parses the patches from the given document. | |---------------------------------------------------------------------------------------|-----------------------------------------------| | [`extract_patch`](#fiftyone.utils.patches.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`](fiftyone.core.collections.md#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.md#fiftyone.core.labels.Detection), [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections), [`fiftyone.core.labels.Polyline`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline), or [`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#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.md#fiftyone.core.labels.Detection), [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections), [`fiftyone.core.labels.Polyline`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline), or [`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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