fiftyone.utils.scale#

Utilities for working with annotations in Scale AI format.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Functions:

`import_from_scale`(dataset, labels_dir_or_json)	Imports the Scale AI labels into the FiftyOne dataset.
`export_to_scale`(sample_collection, json_path)	Exports labels from the FiftyOne samples to Scale AI format.
`convert_scale_export_to_import`(inpath, outpath)	Converts a Scale AI JSON export generated by `export_to_scale()` into the format expected by `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:

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:

[
    {
        "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:

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:

{
    "annotations": [...]
    "global_attributes": {...}
}

Semantic Segmentation Annotation:

{
    "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:
```
{
    "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:
```
[
    {
        "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:
```
{
    "events": [...]
}
```
Video Playback:
```
{
    "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:
```
{
    "annotations": {...}
}
```
The optional events file should contain a list of events in the video:
```
{
    "events": [...]
}
```

Parameters:

dataset – a 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:

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

{
    <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:
```
{
    "annotations": [...],
    "global_attributes": {...}
}
```

Video samples:

{
    "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:

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:

[
    {
        "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:

{
    "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:

{
    "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:

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

where each per-sample JSON file contains the events in the video:

{
    "events": [...]
}

Parameters:

sample_collection – a 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 task. By default, video labels are exported for in a suitable format for the 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() into the format expected by 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()
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