fiftyone.utils.annotations

module documentation

(source)

Annotation utilities.

Class	`AnnotationAPI`	Base class for APIs that connect to annotation backends.
Class	`AnnotationBackend`	Base class for annotation backends.
Class	`AnnotationBackendConfig`	Base class for configuring an `AnnotationBackend` instances.
Class	`AnnotationResults`	Base class for storing the intermediate results of an annotation run that has been initiated and is waiting for its results to be merged back into the FiftyOne dataset.
Class	`DrawConfig`	No summary
Function	`annotate`	Exports the samples and optional label field(s) to the given annotation backend.
Function	`connect_to_api`	Returns an API instance connected to the annotation backend.
Function	`draw_labeled_image`	Renders an annotated version of the sample's image with the specified label data overlaid to disk.
Function	`draw_labeled_images`	Renders annotated versions of the images in the collection with the specified label data overlaid to the given directory.
Function	`draw_labeled_video`	Renders an annotated version of the sample's video with the specified label data overlaid to disk.
Function	`draw_labeled_videos`	Renders annotated versions of the videos in the collection with the specified label data overlaid to the given directory.
Function	`load_annotations`	Downloads the labels from the given annotation run from the annotation backend and merges them into the collection.
Variable	`logger`	Undocumented
Function	`_build_label_schema`	Undocumented
Function	`_ensure_label_field`	Undocumented
Function	`_flatten_list`	Undocumented
Function	`_format_attributes`	Undocumented
Function	`_get_attributes`	Undocumented
Function	`_get_backend_field_type`	Undocumented
Function	`_get_classes`	Undocumented
Function	`_get_frame_labels`	Undocumented
Function	`_get_label_attributes`	Undocumented
Function	`_get_label_type`	Undocumented
Function	`_get_mask_targets`	Undocumented
Function	`_get_patches_view_label_ids`	Undocumented
Function	`_get_sample_labels`	Undocumented
Function	`_get_skeleton`	Undocumented
Function	`_get_writeable_attributes`	Undocumented
Function	`_handle_frame_fields`	Undocumented
Function	`_init_label_schema`	Undocumented
Function	`_is_trackable_field`	Undocumented
Function	`_merge_label`	Undocumented
Function	`_merge_labels`	Undocumented
Function	`_merge_scalars`	Undocumented
Function	`_parse_attributes`	Undocumented
Function	`_parse_classes_dict`	Undocumented
Function	`_parse_config`	Undocumented
Function	`_parse_draw_config`	Undocumented
Function	`_prompt_field`	Undocumented
Function	`_select_labels_with_type`	Undocumented
Function	`_to_image_labels`	Undocumented
Function	`_to_list`	Undocumented
Function	`_to_video_labels`	Undocumented
Function	`_unwrap`	Undocumented
Function	`_update_tracks`	Undocumented
Constant	`_DEFAULT_LABEL_FIELDS_MAP`	Undocumented
Constant	`_LABEL_TYPES`	Undocumented
Constant	`_LABEL_TYPES_MAP`	Undocumented
Constant	`_RETURN_TYPES_MAP`	Undocumented
Constant	`_SPATIAL_LABEL_FIELDS_MAP`	Undocumented
Constant	`_SPATIAL_TYPES`	Undocumented
Constant	`_TRACKABLE_TYPES`	Undocumented

def annotate(samples, anno_key, label_schema=None, label_field=None, label_type=None, classes=None, attributes=True, mask_targets=None, allow_additions=True, allow_deletions=True, allow_label_edits=True, allow_index_edits=True, allow_spatial_edits=True, media_field='filepath', backend=None, launch_editor=False, **kwargs): (source) ¶

Exports the samples and optional label field(s) to the given annotation backend.

The backend parameter controls which annotation backend to use. Depending on the backend you use, you may want/need to provide extra keyword arguments to this function for the constructor of the backend's AnnotationBackendConfig class.

The natively provided backends and their associated config classes are:

"cvat": fiftyone.utils.cvat.CVATBackendConfig
"labelstudio": fiftyone.utils.labelstudio.LabelStudioBackendConfig
"labelbox": fiftyone.utils.labelbox.LabelboxBackendConfig

See :ref:`this page <requesting-annotations>` for more information about using this method, including how to define label schemas and how to configure login credentials for your annotation provider.

Parameters
samples	a `fiftyone.core.collections.SampleCollection`
anno_key	a string key to use to refer to this annotation run
label_schema:`None`	a dictionary defining the label schema to use. If this argument is provided, it takes precedence over the other schema-related arguments
label_field:`None`	a string indicating a new or existing label field to annotate
label_type:`None`	a string indicating the type of labels to annotate. The possible values are: `"classification"`: a single classification stored in `fiftyone.core.labels.Classification` fields `"classifications"`: multilabel classifications stored in `fiftyone.core.labels.Classifications` fields `"detections"`: object detections stored in `fiftyone.core.labels.Detections` fields `"instances"`: instance segmentations stored in `fiftyone.core.labels.Detections` fields with their `mask` attributes populated `"polylines"`: polylines stored in `fiftyone.core.labels.Polylines` fields with their `filled` attributes set to `False` `"polygons"`: polygons stored in `fiftyone.core.labels.Polylines` fields with their `filled` attributes set to `True` `"keypoints"`: keypoints stored in `fiftyone.core.labels.Keypoints` fields `"segmentation"`: semantic segmentations stored in `fiftyone.core.labels.Segmentation` fields `"scalar"`: scalar labels stored in `fiftyone.core.fields.IntField`, `fiftyone.core.fields.FloatField`, `fiftyone.core.fields.StringField`, or `fiftyone.core.fields.BooleanField` fields All new label fields must have their type specified via this argument or in `label_schema`. Note that annotation backends may not support all label types
classes:`None`	a list of strings indicating the class options for `label_field` or all fields in `label_schema` without classes specified. All new label fields must have a class list provided via one of the supported methods. For existing label fields, if classes are not provided by this argument nor `label_schema`, the observed labels on your dataset are used
attributes:`True`	specifies the label attributes of each label field to include (other than their `label`, which is always included) in the annotation export. Can be any of the following: `True`: export all label attributes `False`: don't export any custom label attributes an attribute or list of attributes to export a dict mapping attribute names to dicts specifying the details of the attribute field If a `label_schema` is also provided, this parameter determines which attributes are included for all fields that do not explicitly define their per-field attributes (in addition to any per-class attributes)
mask_targets:`None`	a dict mapping pixel values to semantic label strings. Only applicable when annotating semantic segmentations. All new label fields must have mask targets provided via one of the supported methods. For existing label fields, if mask targets are not provided by this argument nor `label_schema`, any applicable mask targets stored on your dataset will be used, if available
allow_additions:`True`	whether to allow new labels to be added. Only applicable when editing existing label fields
allow_deletions:`True`	whether to allow labels to be deleted. Only applicable when editing existing label fields
allow_label_edits:`True`	whether to allow the `label` attribute of existing labels to be modified. Only applicable when editing existing fields with `label` attributes
allow_index_edits:`True`	whether to allow the `index` attribute of existing video tracks to be modified. Only applicable when editing existing frame fields with `index` attributes
allow_spatial_edits:`True`	whether to allow edits to the spatial properties (bounding boxes, vertices, keypoints, masks, etc) of labels. Only applicable when editing existing spatial label fields
media_field:"filepath"	the field containing the paths to the media files to upload
backend:`None`	the annotation backend to use. The supported values are `fiftyone.annotation_config.backends.keys()` and the default is `fiftyone.annotation_config.default_backend`
launch_editor:`False`	whether to launch the annotation backend's editor after uploading the samples
**kwargs	keyword arguments for the `AnnotationBackendConfig` subclass of the backend being used
Returns
an `AnnotationResults`

def connect_to_api(backend=None, **kwargs): (source) ¶

Returns an API instance connected to the annotation backend.

Some annotation backends may not expose this functionality.

Parameters
backend:`None`	the annotation backend to use. The supported values are `fiftyone.annotation_config.backends.keys()` and the default is `fiftyone.annotation_config.default_backend`
**kwargs	keyword arguments for the `AnnotationBackendConfig` subclass of the backend being used
Returns
an `AnnotationAPI`

def draw_labeled_image(sample, outpath, label_fields=None, config=None, **kwargs): (source) ¶

Renders an annotated version of the sample's image with the specified label data overlaid to disk.

Parameters
sample	a `fiftyone.core.sample.Sample`
outpath	the path to write the annotated image
label_fields:`None`	a label field or list of label fields to render. If omitted, all compatible fields are rendered
config:`None`	an optional `DrawConfig` configuring how to draw the labels
**kwargs	optional keyword arguments specifying parameters of the default `DrawConfig` to override

def draw_labeled_images(samples, output_dir, rel_dir=None, label_fields=None, config=None, progress=None, **kwargs): (source) ¶

Renders annotated versions of the images in the collection with the specified label data overlaid to the given directory.

The filenames of the sample images are maintained, unless a name conflict would occur in output_dir, in which case an index of the form "-%d" % count is appended to the base filename.

The images are written in format fo.config.default_image_ext.

Parameters
samples	a `fiftyone.core.collections.SampleCollection`
output_dir	the directory to write the annotated images
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 annotated image. This argument allows for populating nested subdirectories in `output_dir` that match the shape of the input paths. The path is converted to an absolute path (if necessary) via `fiftyone.core.storage.normalize_path`
label_fields:`None`	a label field or list of label fields to render. If omitted, all compatible fields are rendered
config:`None`	an optional `DrawConfig` configuring how to draw the labels
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
**kwargs	optional keyword arguments specifying parameters of the default `DrawConfig` to override
Returns
the list of paths to the labeled images

def draw_labeled_video(sample, outpath, support=None, label_fields=None, config=None, **kwargs): (source) ¶

Renders an annotated version of the sample's video with the specified label data overlaid to disk.

Parameters
sample	a `fiftyone.core.sample.Sample`
outpath	the path to write the annotated image
support:`None`	an optional `[first, last]` range of frames to render
label_fields:`None`	a label field or list of label fields to render. If omitted, all compatible fields are rendered
config:`None`	an optional `DrawConfig` configuring how to draw the labels
**kwargs	optional keyword arguments specifying parameters of the default `DrawConfig` to override

def draw_labeled_videos(samples, output_dir, rel_dir=None, label_fields=None, config=None, progress=None, **kwargs): (source) ¶

Renders annotated versions of the videos in the collection with the specified label data overlaid to the given directory.

The filenames of the videos are maintained, unless a name conflict would occur in output_dir, in which case an index of the form "-%d" % count is appended to the base filename.

The videos are written in format fo.config.default_video_ext.

Parameters
samples	a `fiftyone.core.collections.SampleCollection`
output_dir	the directory to write the annotated videos
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 annotated video. This argument allows for populating nested subdirectories in `output_dir` that match the shape of the input paths. The path is converted to an absolute path (if necessary) via `fiftyone.core.storage.normalize_path`
label_fields:`None`	a label field or list of label fields to render. If omitted, all compatible fields are rendered
config:`None`	an optional `DrawConfig` configuring how to draw the labels
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
**kwargs	optional keyword arguments specifying parameters of the default `DrawConfig` to override
Returns
the list of paths to the labeled videos

def load_annotations(samples, anno_key, dest_field=None, unexpected='prompt', cleanup=False, progress=None, **kwargs): (source) ¶

Downloads the labels from the given annotation run from the annotation backend and merges them into the collection.

See :ref:`this page <loading-annotations>` for more information about using this method to import annotations that you have scheduled by calling annotate.

Parameters
samples	a `fiftyone.core.collections.SampleCollection`
anno_key	an annotation key
dest_field:`None`	an optional name of a new destination field into which to load the annotations, or a dict mapping field names in the run's label schema to new destination field names
unexpected:"prompt"	how to deal with any unexpected labels that don't match the run's label schema when importing. The supported values are: `"prompt"`: present an interactive prompt to direct/discard unexpected labels `"ignore"`: automatically ignore any unexpected labels `"keep"`: automatically keep all unexpected labels in a field whose name matches the the label type `"return"`: return a dict containing all unexpected labels, or `None` if there aren't any
cleanup:`False`	whether to delete any informtation regarding this run from the annotation backend after loading the annotations
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
**kwargs	keyword arguments for the run's `fiftyone.core.annotation.AnnotationMethodConfig.load_credentials` method
Returns
`None`, unless `unexpected=="return"` and unexpected labels are found, in which case a dict containing the extra labels is returned

logger = (source) ¶

Undocumented

def _build_label_schema(samples, backend, label_schema, label_field, label_type, classes, attributes, mask_targets, allow_additions, allow_deletions, allow_label_edits, allow_index_edits, allow_spatial_edits): (source) ¶

Undocumented

def _ensure_label_field(dataset, label_field, fo_label_type): (source) ¶

Undocumented

def _flatten_list(values): (source) ¶

Undocumented

def _format_attributes(backend, attributes): (source) ¶

Undocumented

def _get_attributes(samples, backend, attributes, label_field, label_info, existing_field, label_type, classes=None): (source) ¶

Undocumented

def _get_backend_field_type(backend, field): (source) ¶

Undocumented

def _get_classes(samples, backend, classes, label_field, label_info, existing_field, label_type): (source) ¶

Undocumented

def _get_frame_labels(sample, frame_label_fields): (source) ¶

Undocumented

def _get_label_attributes(samples, backend, label_field, label_type, classes=None): (source) ¶

Undocumented

def _get_label_type(samples, backend, label_type, label_field, label_info): (source) ¶

Undocumented

def _get_mask_targets(samples, mask_targets, label_field, label_info, existing_field): (source) ¶

Undocumented

def _get_patches_view_label_ids(patches_view): (source) ¶

Undocumented

def _get_sample_labels(sample, label_fields): (source) ¶

Undocumented

def _get_skeleton(samples, label_fields=None): (source) ¶

Undocumented

def _get_writeable_attributes(attributes): (source) ¶

Undocumented

def _handle_frame_fields(dataset, field, ref_field): (source) ¶

Undocumented

def _init_label_schema(label_field, label_type, classes, attributes, mask_targets, allow_additions, allow_deletions, allow_label_edits, allow_index_edits, allow_spatial_edits): (source) ¶

Undocumented

def _is_trackable_field(samples, label_field, label_type): (source) ¶

Undocumented

def _merge_label(label, anno_label, global_attrs=None, class_attrs=None, allow_label_edits=True, allow_index_edits=True, allow_spatial_edits=True, only_keyframes=False): (source) ¶

Undocumented

def _merge_labels(dataset, anno_dict, results, label_field, label_type, label_info=None, global_attrs=None, class_attrs=None, progress=None): (source) ¶

Undocumented

def _merge_scalars(dataset, anno_dict, results, label_field, label_info=None, progress=None): (source) ¶

Undocumented

def _parse_attributes(label_info): (source) ¶

Undocumented

def _parse_classes_dict(d, samples, backend, label_field, existing_field, label_type): (source) ¶

Undocumented

def _parse_config(name, label_schema, **kwargs): (source) ¶

Undocumented

def _parse_draw_config(config, kwargs, samples=None, label_fields=None): (source) ¶

Undocumented

def _prompt_field(dataset, label_type, label_field, label_schema, is_frames_view): (source) ¶

Undocumented

def _select_labels_with_type(samples, label_field, label_type): (source) ¶

Undocumented

def _to_image_labels(sample, label_fields=None): (source) ¶

Undocumented

def _to_list(value): (source) ¶

Undocumented

def _to_video_labels(sample, label_fields=None): (source) ¶

Undocumented

def _unwrap(value): (source) ¶

Undocumented

def _update_tracks(dataset, label_field, anno_dict, only_keyframes): (source) ¶

Undocumented

_DEFAULT_LABEL_FIELDS_MAP = (source) ¶

Undocumented

Value

{fol.Classification: ['label'],
 fol.Detection: ['label', 'index'],
 fol.Polyline: ['label', 'index'],
 fol.Keypoint: ['label', 'index']}

_LABEL_TYPES: tuple[str, ...] = (source) ¶

Undocumented

Value

('classifications', 'detections', 'polylines', 'keypoints')

_LABEL_TYPES_MAP = (source) ¶

Undocumented

Value

{'classification': fol.Classification,
 'classifications': fol.Classifications,
 'detection': fol.Detection,
 'detections': fol.Detections,
 'instance': fol.Detection,
 'instances': fol.Detections,
 'polyline': fol.Polyline,
...

_RETURN_TYPES_MAP: dict[str, str] = (source) ¶

Undocumented

Value

{'classification': 'classifications',
 'classifications': 'classifications',
 'detection': 'detections',
 'detections': 'detections',
 'instance': 'detections',
 'instances': 'detections',
 'polyline': 'polylines',
...

_SPATIAL_LABEL_FIELDS_MAP = (source) ¶

Undocumented

Value

{fol.Detection: ['bounding_box', 'mask'],
 fol.Polyline: ['points', 'closed', 'filled'],
 fol.Keypoint: ['points'],
 fol.Segmentation: ['mask']}

_SPATIAL_TYPES: tuple[str, ...] = (source) ¶

Undocumented

Value

('detections', 'polylines', 'keypoints', 'segmentation')

_TRACKABLE_TYPES: tuple[str, ...] = (source) ¶

Undocumented

Value

('detections', 'polylines', 'keypoints')