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,
):
    """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
    :class:`AnnotationBackendConfig` class.

    The natively provided backends and their associated config classes are:

    -   ``"cvat"``: :class:`fiftyone.utils.cvat.CVATBackendConfig`
    -   ``"labelstudio"``: :class:`fiftyone.utils.labelstudio.LabelStudioBackendConfig`
    -   ``"labelbox"``: :class:`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.

    Args:
        samples: a :class:`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
                :class:`fiftyone.core.labels.Classification` fields
            -   ``"classifications"``: multilabel classifications stored in
                :class:`fiftyone.core.labels.Classifications` fields
            -   ``"detections"``: object detections stored in
                :class:`fiftyone.core.labels.Detections` fields
            -   ``"instances"``: instance segmentations stored in
                :class:`fiftyone.core.labels.Detections` fields with their
                :attr:`mask <fiftyone.core.labels.Detection.mask>` attributes
                populated
            -   ``"polylines"``: polylines stored in
                :class:`fiftyone.core.labels.Polylines` fields with their
                :attr:`filled <fiftyone.core.labels.Polyline.filled>`
                attributes set to ``False``
            -   ``"polygons"``: polygons stored in
                :class:`fiftyone.core.labels.Polylines` fields with their
                :attr:`filled <fiftyone.core.labels.Polyline.filled>`
                attributes set to ``True``
            -   ``"keypoints"``: keypoints stored in
                :class:`fiftyone.core.labels.Keypoints` fields
            -   ``"segmentation"``: semantic segmentations stored in
                :class:`fiftyone.core.labels.Segmentation` fields
            -   ``"scalar"``: scalar labels stored in
                :class:`fiftyone.core.fields.IntField`,
                :class:`fiftyone.core.fields.FloatField`,
                :class:`fiftyone.core.fields.StringField`, or
                :class:`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 :class:`AnnotationBackendConfig`
            subclass of the backend being used

    Returns:
        an :class:`AnnotationResults`
    """

    # Convert to equivalent regular view containing the same labels
    if samples._dataset._is_patches:
        ids = _get_patches_view_label_ids(samples)
        samples = samples._root_dataset.select_labels(
            ids=ids,
            fields=samples._label_fields,
        )

    if not samples:
        raise ValueError(
            "%s is empty; there is nothing to annotate"
            % samples.__class__.__name__
        )

    config = _parse_config(backend, None, media_field=media_field, **kwargs)
    anno_backend = config.build()
    anno_backend.ensure_requirements()

    supported_media_types = anno_backend.supported_media_types
    if samples.media_type not in supported_media_types:
        if samples.media_type == fomm.GROUP:
            raise fomm.SelectGroupSlicesError(supported_media_types)

        raise fomm.MediaTypeError(
            "The '%s' backend does not supported annotating '%s' collections"
            % (anno_backend.config.name, samples.media_type)
        )

    if samples._is_clips and not anno_backend.supports_clips_views:
        raise ValueError(
            "Backend '%s' does not support annotating clips views"
            % anno_backend.config.name
        )

    label_schema, samples = _build_label_schema(
        samples,
        anno_backend,
        label_schema,
        label_field,
        label_type,
        classes,
        attributes,
        mask_targets,
        allow_additions,
        allow_deletions,
        allow_label_edits,
        allow_index_edits,
        allow_spatial_edits,
    )
    config.label_schema = label_schema

    # Don't allow overwriting an existing run with same `anno_key`, since we
    # need the existing run in order to perform workflows like automatically
    # cleaning up the backend's tasks
    anno_backend.register_run(samples, anno_key, overwrite=False)

    results = anno_backend.upload_annotations(
        samples, anno_key, launch_editor=launch_editor
    )

    results._finalize_id_map()

    anno_backend.save_run_results(samples, anno_key, results)

    return results
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
    :class:`AnnotationBackendConfig` class.

    The natively provided backends and their associated config classes are:

    -   ``"cvat"``: :class:`fiftyone.utils.cvat.CVATBackendConfig`
    -   ``"labelstudio"``: :class:`fiftyone.utils.labelstudio.LabelStudioBackendConfig`
    -   ``"labelbox"``: :class:`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.

    Args:
        samples: a :class:`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
                :class:`fiftyone.core.labels.Classification` fields
            -   ``"classifications"``: multilabel classifications stored in
                :class:`fiftyone.core.labels.Classifications` fields
            -   ``"detections"``: object detections stored in
                :class:`fiftyone.core.labels.Detections` fields
            -   ``"instances"``: instance segmentations stored in
                :class:`fiftyone.core.labels.Detections` fields with their
                :attr:`mask <fiftyone.core.labels.Detection.mask>` attributes
                populated
            -   ``"polylines"``: polylines stored in
                :class:`fiftyone.core.labels.Polylines` fields with their
                :attr:`filled <fiftyone.core.labels.Polyline.filled>`
                attributes set to ``False``
            -   ``"polygons"``: polygons stored in
                :class:`fiftyone.core.labels.Polylines` fields with their
                :attr:`filled <fiftyone.core.labels.Polyline.filled>`
                attributes set to ``True``
            -   ``"keypoints"``: keypoints stored in
                :class:`fiftyone.core.labels.Keypoints` fields
            -   ``"segmentation"``: semantic segmentations stored in
                :class:`fiftyone.core.labels.Segmentation` fields
            -   ``"scalar"``: scalar labels stored in
                :class:`fiftyone.core.fields.IntField`,
                :class:`fiftyone.core.fields.FloatField`,
                :class:`fiftyone.core.fields.StringField`, or
                :class:`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 :class:`AnnotationBackendConfig`
            subclass of the backend being used

    Returns:
        an :class:`AnnotationResults`
    
fiftyone/utils/annotations.py