fiftyone.utils.scale

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.

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
• General Video Annotation
• Video Playback

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": [...]
}

Imports the Scale AI labels into the FiftyOne dataset.

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

• General Image Annotation
• Semantic Segmentation Annotation
• General Video Annotation
• 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:

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