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

# fiftyone.utils.scale

Utilities for working with annotations in
[Scale AI format](https://docs.scale.com/reference/introduction).

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

**Functions:**

| [`import_from_scale`](#fiftyone.utils.scale.import_from_scale)(dataset, labels_dir_or_json)               | Imports the Scale AI labels into the FiftyOne dataset.                                                                                                                                                  |
|-----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`export_to_scale`](#fiftyone.utils.scale.export_to_scale)(sample_collection, json_path)                  | Exports labels from the FiftyOne samples to Scale AI format.                                                                                                                                            |
| [`convert_scale_export_to_import`](#fiftyone.utils.scale.convert_scale_export_to_import)(inpath, outpath) | Converts a Scale AI JSON export generated by [`export_to_scale()`](#fiftyone.utils.scale.export_to_scale) into the format expected by [`import_from_scale()`](#fiftyone.utils.scale.import_from_scale). |

### fiftyone.utils.scale.import_from_scale(dataset, labels_dir_or_json, label_prefix=None, scale_id_field='scale_id', progress=None)

Imports the Scale AI labels into the FiftyOne dataset.

This method supports importing annotations from the following Scale API
endpoints:

- [General Image Annotation](https://docs.scale.com/reference/general-image-annotation)
- [Semantic Segmentation Annotation](https://docs.scale.com/reference/semantic-segmentation-annotation)
- [General Video Annotation](https://docs.scale.com/reference/general-video-annotation)
- [Video Playback](https://docs.scale.com/reference/video-playback)

The `scale_id_field` of the FiftyOne samples are used to associate
samples with their corresponding Scale task IDs.

The provided `labels_dir_or_json` can either be the path to a JSON
export in the following format:

```default
[
    {
        "task_id": <scale-task-id1>,
        "response": {...},
        ...
    },
    {
        "task_id": <scale-task-id2>,
        "response": {...},
        ...
    },
    ...
]
```

or a directory of per-task JSON files, which can either (a) directly
contain the elements of the list above, or (b) contain task labels
organized in the following format:

```default
labels_dir/
    <scale-task-id1>.json
    <scale-task-id2>.json
    ...
```

where each JSON file contains only the contents of the `response` field
for the task.

The contents of the `response` field should be as follows:

- [General Image Annotation](https://docs.scale.com/reference/general-image-annotation):
  ```default
  {
      "annotations": [...]
      "global_attributes": {...}
  }
  ```
- [Semantic Segmentation Annotation](https://docs.scale.com/reference/semantic-segmentation-annotation):
  ```default
  {
      "annotations": {
          ...
          "combined": {
              ...
              "indexedImage": <url-or-filepath>
          }
      },
      "labelMapping": {...}
  }
  ```

  where the `indexedImage` field (which is the only version of the
  segmentation used by this method) can contain either a URL, in which
  case the mask is downloaded from the web, or the path to the mask on
  disk.
- [General Video Annotation](https://docs.scale.com/reference/general-video-annotation):
  ```default
  {
      "annotations": {
          "url": <url-or-filepath>
      },
      "events": {
          "url": <url-or-filepath>
      }
  }
  ```

  where the `url` fields can contain either a URL, in which case the
  file is downloaded from the web, or the path to JSON file on disk.

  The annotations file should contain per-frame annotations in the
  following format:
  ```default
  [
      {
          "annotations": [...],
          "global_attributes": {...}
      },
      {
          "annotations": [...],
          "global_attributes": {...}
      },
      ...
  ]
  ```

  where the n-th element in the list contains the labels for the n-th
  frame that was labeled.

  Note that, if parameters such as `duration_time`, `frame_rate`, and
  `start_time` were used to specify which frames of the video to
  annotate, then you must ensure that the `labels_dir_or_json` JSON
  that you provide to this method contains the `task` fields for each
  Scale task so that the correct frame numbers can be determined from
  these values.

  The optional events file should contain a list of events in the video:
  ```default
  {
      "events": [...]
  }
  ```
- [Video Playback](https://docs.scale.com/reference/video-playback):
  ```default
  {
      "annotations": {
          "url": <url-or-filepath>
      },
      "events": {
          "url": <url-or-filepath>
      }
  }
  ```

  where the `url` fields can contain either a URL, in which case the
  file is downloaded from the web, or the path to JSON files on disk.

  The annotations file should contain a dictionary of object
  trajectories:
  ```default
  {
      "annotations": {...}
  }
  ```

  The optional events file should contain a list of events in the video:
  ```default
  {
      "events": [...]
  }
  ```

* **Parameters:**
  * **dataset** – a [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset)
  * **labels_dir_or_json** – the path to a Scale AI JSON export or a directory
    of JSON exports as per the formats described above
  * **label_prefix** (*None*) – a prefix to prepend to the sample label field(s)
    that are created, separated by an underscore
  * **scale_id_field** ( *"scale_id"*) – the sample field to use to associate Scale
    task IDs with FiftyOne samples
  * **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.scale.export_to_scale(sample_collection, json_path, video_labels_dir=None, video_events_dir=None, video_playback=False, label_field=None, frame_labels_field=None, progress=None)

Exports labels from the FiftyOne samples to Scale AI format.

This function is useful for generating pre-annotations that can be provided
to Scale AI via the `hypothesis` parameter of the following endpoints:

- [General Image Annotation](https://docs.scale.com/reference/general-image-annotation)
- [General Video Annotation](https://docs.scale.com/reference/general-video-annotation)
- [Video Playback](https://docs.scale.com/reference/video-playback)

The output `json_path` will be a JSON file in the following format:

```default
{
    <sample-id1>: {
        "filepath": <filepath1>,
        "hypothesis": {...}
    },
    <sample-id2>: {
        "filepath": <filepath2>,
        "hypothesis": {...}
    },
    ...
}
```

The format of the `hypothesis` field depends on the label type:

- Sample-level classifications, detections, polylines, polygons, and
  keypoints:
  ```default
  {
      "annotations": [...],
      "global_attributes": {...}
  }
  ```
- Video samples:
  ```default
  {
      "annotations": {
          "url": <filepath>
      }
  }
  ```

When exporting labels for video datasets, the `url` field will contain
the paths on disk to per-sample JSON files that are written to
`video_labels_dir` as follows:

```default
video_labels_dir/
    <sample-id1>.json
    <sample-id2>.json
    ...
```

When `video_playback == False`, the per-sample JSON files are written in
[General Video Annotation format](https://docs.scale.com/reference/general-video-annotation):

```default
[
    {
        "annotations": [...],
        "global_attributes": {...}
    },
    {
        "annotations": [...],
        "global_attributes": {...}
    },
    ...
]
```

where the n-th element in the list contains the labels for the n-th frame
of the video.

When `video_playback == True`, the per-sample JSON files are written in
[Video Playback format](https://docs.scale.com/reference/video-playback):

```default
{
    "annotations": {...}
}
```

When exporting labels for videos and the `video_events_dir` parameter is
provided, the `hypothesis` fields of the JSON written to `json_path`
will include an `events` field:

```default
{
    "annotations": {
        "url": <filepath>
    },
    "events": {
        "url": <filepath>
    }
}
```

whose `url` field will contain the paths on disk to per-sample JSON files
that are written to `video_events_dir` as follows:

```default
video_events_dir/
    <sample-id1>.json
    <sample-id2>.json
    ...
```

where each per-sample JSON file contains the
[events in the video](https://docs.scale.com/reference/events):

```default
{
    "events": [...]
}
```

* **Parameters:**
  * **sample_collection** – a
    [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
  * **json_path** – the path to write the JSON export
  * **video_labels_dir** (*None*) – a directory to write the per-sample video
    labels. Only applicable for video datasets
  * **video_events_dir** (*None*) – a directory to write the per-sample video
    events. Only applicable for video datasets
  * **video_playback** (*False*) – 

    whether to export video labels in a suitable
    format for use with the
    [Video Playback](https://docs.scale.com/reference/video-playback) task.
    By default, video labels are exported for in a suitable format for
    the [General Video Annotation](https://docs.scale.com/reference/general-video-annotation)
    task. Only applicable for video datasets
  * **label_field** (*None*) – 

    optional label field(s) to export. Can be any of
    the following:
    - the name of a label field to export
    - a glob pattern of label field(s) to export
    - a list or tuple of label field(s) to export
    - a dictionary mapping label field names to keys to use when
      constructing the exported labels

    By default, no labels are exported
  * **frame_labels_field** (*None*) – 

    optional frame label field(s) to export.
    Only applicable to video datasets. Can be any of the following:
    - the name of a frame label field to export
    - a glob pattern of frame label field(s) to export
    - a list or tuple of frame label field(s) to export
    - a dictionary mapping frame label field names to keys to use
      when constructing the exported frame labels

    By default, no frame labels are exported
  * **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.scale.convert_scale_export_to_import(inpath, outpath)

Converts a Scale AI JSON export generated by [`export_to_scale()`](#fiftyone.utils.scale.export_to_scale)
into the format expected by [`import_from_scale()`](#fiftyone.utils.scale.import_from_scale).

The output JSON file will have the same format that is generated when
performing a bulk export of a Scale AI project’s labels.

* **Parameters:**
  * **inpath** – the path to an JSON file generated (for example) by
    [`export_to_scale()`](#fiftyone.utils.scale.export_to_scale)
  * **outpath** – the path to write a JSON file containing the converted labels
* **Returns:**
  a dictionary mapping sample IDs to the task IDs that were generated for
  each sample