Exporting Annotations

Overview of exporting annotations from Ango Hub

Administrators and project managers can create and download an export of all annotations performed in a project on Ango Hub.

If the project you are attempting to obtain the export for contains individual videos with more than ~50k annotated frames, in order to obtain the export for that video, you must enable the Only Key Frames option to attempt to reduce the number of annotations that are exported.

Exporting videos with more than 50k frames, each with annotations, would require manual intervention from the dev team. Please contact us in case this is required.

Getting your Export

Enter your project's Export tab. The Export button at the bottom will allow you to download your annotations.

You will receive a notification within Ango Hub when the export is ready. You may navigate away from the page while the export is being prepared.

Using Custom Private Buckets for Exports

By default, after Ango Hub has computed the export, it uploads it to iMerit's own private bucket, and presents it to you as a signed URL from which you will be able to download it. When you click on the link, you are downloading the export as it is found in iMerit's private bucket.

In case this is not an option for you for data security reasons, or if you'd like to automatically collect your exports in a private bucket of your choice, you may have Ango Hub send the export to a bucket of your choice instead of iMerit's. Here are the steps to accomplish this:

1. From your project's dashboard, navigate to the Settings tab, then enter the General section.

2. Enable the Export Storage toggle. The Export Storage details will appear:

1. Pick a storage from the first dropdown. If you have not yet set up a storage within Ango Hub, please follow this guide for AWS S3 and this guide for Google Cloud Platform.
2. In the Bucket field, enter the name of the bucket where you'd like to receive your exports.

3. In the Path field, enter the folder where you'd like to receive your exports, followed by slashes and names of subfolders if any. Folders will be created if they do not exist.

For example, to obtain your exports in a folder called exports located on the root of your bucket, simply write exports. To get them in a subfolder of exports called 2023, write exports/2023.

1. Click on Save at the bottom of the page.

Now, when you obtain the export in this project, the export .zip file will be created directly within the bucket you specified, and when you click on the notification to download it, you will be downloading it directly from your own bucket. This also includes exports obtained from export-type plugins.

For exports obtained with Export Plugins, Hub will save to the bucket both the original export in Ango Export Format and the converted export.

Export Options

Export Format

You can download your export in the JSON, NDJSON, and NDJSON (Split) formats.

For more details on our export format, please consult the docs page on the Ango Export Format.

If you need to download your export in more, different formats, we recommend you use our Export Converter Plugins.

We have developed the JSON export format to be as easy to parse and convert to other formats as possible. If you need your annotations in a format that is not supported by our plugins and you are a paid customer, contact us and we will provide you a script to convert our JSON export to the format of your choice.

Stage

By default, the export will contain only tasks in the Complete stage. From this field, however, you can pick the stages you wish to get the export for.

Fields

Click on the checkboxes next to the desired fields to include them in the export. Details of each toggle are as follows:

Toggle	Description	Format
Annotation Metadata	Metadata regarding each individual annotation in the task.	"metadata": { "createdAt": "2023-02-02T08:06:03.263Z", "createdBy": "Lorenzo Gravina", "updatedAt": "2023-02-02T08:06:07.276Z", "updatedBy": "Lorenzo Gravina" }
Stage History	Object containing, for each task, its stage history, so which stages it has traveled through and for how long.	"stageHistory": [ { "_id": "64774fb6e58cac001554d9e0", "stageId": "Start", "duration": 0, "completedAt": "2023-05-31T13:46:30.942Z", "stageName": "Start" }, { "_id": "64774fc8e58cac001554da05", "stageId": "bd112eb0-a8e4-418b-b1fb-fa728316e36e", "taskHistory": "64774fc8e58cac001554da03", "duration": 11893, "submittedBy": "[e-mail]", "completedAt": "2023-05-31T13:46:48.358Z", "completedBy": "[e-mail]", "consensusId": "d3292fa9-4b8c-4237-86f0-8e8a79adfb4b", "stageName": "Consensus_1" }, { "_id": "64774fe2e58cac001554da5d", "stageId": "4758ed37-61c7-4a63-8362-fd36cf48e14f", "taskHistory": "64774fe2e58cac001554da5b", "duration": 18734, "submittedBy": "[e-mail]", "completedAt": "2023-05-31T13:47:14.883Z", "completedBy": "[e-mail]", "consensusId": "d3292fa9-4b8c-4237-86f0-8e8a79adfb4b", "stageName": "Consensus_2" } ]
Only Key Frames	When toggled, for video assets, only include key frames. Do not include interpolation frames. In other words, the export will only include frames in which a tool or frame-specific classification has been edited or toggled on/off.

Send Link as an Email

When this is active, you will receive an email with a link to your export when it is ready.

Export History

From the Export tab of a project, by clicking on the Export History section, you may access a history of the exports that have been obtained for that project before and redownload them.

Legacy Export

By default, you will be downloading the export in our latest format. This format was created to support our workflow feature, and contains full annotations for each stage each task has been through.

If a task went through multiple labeling stages, for example as a result of consensus, by downloading an up-to-date export, you will get all annotations from all of the stages instead of the regular export, which only contains the 'final' annotations.

So for example, if you have a consensus stage in your workflow and you wish to export all annotations (aka "judgments") done by all annotators in consensus, you will need to download an up-to-date export. This also applies to review stages.

Previously, we used to have a different export format (Legacy).

Expand the section below to see what changed between our legacy format and the up-to-date export format.

What's new in Export

Export V3 was designed for the new workflow system. You can see the differences with the previous format below. (click to expand)

Main Changes:

• Instead of multiple tasks in an asset, a single task will be available for every asset.

• totalDuration will be available under each task and it will show the cumulative duration spent in each stage.

• objects field was replaced with tools.

• stageHistory will provide the details about each stage.

The following is an example of a task exported with Stage History enabled and by clicking on Export V3. The main difference is in the stageHistory object, where instead of only having metadata for each stage, we have full annotation information:

{
  "asset": "https://asset.com/4b6cf400-4c8c-407c-ac17-7fc46ff31ed6.jpg",
  "externalId": "id.jpg",
  "metadata": {},
  "batches": [],
  "task": {
    "taskId": "64885625c5c18a0015b9a2b2",
    "stage": "Complete",
    "updatedAt": "2023-06-13T11:43:50.774Z",
    "updatedBy": "[e-mail]",
    "totalDuration": 18069,
    "tools": [
      {
        "bounding-box": {
          "x": 559.1259640102828,
          "y": 370.33893919793013,
          "height": 243.03492884864167,
          "width": 462.72493573264785
        },
        "objectId": "46977649fb0d3fe07aaf604",
        "classifications": [],
        "metadata": {
          "createdAt": 1686656626604,
          "createdBy": "[e-mail]",
          "createdIn": "9c9b1d95-e366-4b43-b2e9-ec8a23b65792"
        },
        "schemaId": "f85d16526793ef2df7da359",
        "title": "BB"
      }
    ],
    "classifications": [
      {
        "objectId": "6cd4e0c70542b29a457d908",
        "schemaId": "6c1eaa823dcda15716b0591",
        "tool": "radio",
        "title": "Rad",
        "answer": "2",
        "classifications": []
      }
    ],
    "relations": [],
    "stageHistory": [
      {
        "stage": "Start",
        "duration": 0,
        "completedAt": "2023-06-13T11:42:29.055Z",
        "tools": [],
        "classifications": [],
        "relations": []
      },
      {
        "stage": "Consensus_1",
        "duration": 10354,
        "completedAt": "2023-06-13T11:43:39.195Z",
        "completedBy": "[e-mail]",
        "tools": [
          {
            "bounding-box": {
              "x": 562.9820051413873,
              "y": 371.62483829236726,
              "height": 239.17723156533017,
              "width": 464.0102827763505
            },
            "objectId": "7e7b8f38d2030a696a1b820",
            "classifications": [],
            "schemaId": "f85d16526793ef2df7da359",
            "title": "BB"
          }
        ],
        "classifications": [
          {
            "objectId": "914504eba860e135cca3810",
            "schemaId": "6c1eaa823dcda15716b0591",
            "tool": "radio",
            "title": "Rad",
            "answer": "1",
            "classifications": []
          }
        ],
        "relations": []
      },
      {
        "stage": "Consensus_2",
        "duration": 7715,
        "completedAt": "2023-06-13T11:43:50.821Z",
        "completedBy": "[e-mail]",
        "tools": [
          {
            "bounding-box": {
              "x": 559.1259640102828,
              "y": 370.33893919793013,
              "height": 243.03492884864167,
              "width": 462.72493573264785
            },
            "objectId": "46977649fb0d3fe07aaf604",
            "classifications": [],
            "schemaId": "f85d16526793ef2df7da359",
            "title": "BB"
          }
        ],
        "classifications": [
          {
            "objectId": "6cd4e0c70542b29a457d908",
            "schemaId": "6c1eaa823dcda15716b0591",
            "tool": "radio",
            "title": "Rad",
            "answer": "2",
            "classifications": []
          }
        ],
        "relations": []
      }
    ]
  }
}

Key Differences

Sample V3 (current) export

115KB

Complete_Export-export-2023-09-01-13_11_48_GMT_v3.json

Sample Legacy Export

380KB

The Demo Project-export-2023-11-08T11_13_38.796Z.zip

archive