Skip to content

Exporting Data & Annotations

Innotescus allows users to export annotations, datasets, or both. Click here to view the tutorial video. Unless specified by the specific export format, each export will have the general folder structure shown below:

/datasets/
  /dataset1
      /image1
      /image2
      /image3
      ⠇
  /dataset2
      /image1
      /image2
      /image3
      ⠇   
  /dataset3
      /image1
      /image2
      /image3
      ⠇    
/annotations
  /task1
    /dataset1
        *task1 dataset1 annotations*
    /dataset2
        *task1 dataset2 annotations*
  /task2
    /dataset1
        *task2 dataset1 annotations*
  /task3
    /dataset3
        *task3 dataset3 annotations*

Generating Exports

To create an export, navigate to the exports tab of a project and click ‘new export.’ After choosing a task, users can filter by dataset and date, and add optional password protection for the download. Once you’ve ‘run export,’ there will be a new entry in the exports table with a download link. View the video below to see the full process.

Export Generation

Below are all of the options available during the export process with brief explanations.

What Would You Like to Export?

Export Type

Users have the option to export datasets, annotations, or both.

Task Selection

If exporting annotations, users must pick one or more tasks to export. After the first task is selected, only other tasks of the same task type and data type will be eligible to include in the same export.

Annotation Format

If one or more tasks have been selected for the export, the 'Annotation Format' field will include all annotation formats compatible with the selected task and data types. For more information on annotation formats, see below.

Choosing Datasets

Dataset Selection

After determining the contents of the export, users must select at least one dataset they'd like to export. If exporting one or more tasks, all datasets assigned to the selected task(s) will be available; the export will only contain annotations for selected datasets. If exporting datasets only, all datasets within the current project will be available.

Export Options

On this step of the export creation process, users can choose to split or filter their exports. Each option is explained in more detail below.

Splitting Exports

If users click the 'split my export' checkbox under the dataset selection window, an extra step appears in the export process that will allow them to split their export into any number of subsets. Users can choose standard splits from the dropdown, or create their own. Data and annotations from separate datasets will be combined into each split, and no longer segregated by dataset.

Filtering Exports

Clicking the 'filter my export' checkbox under the dataset selection window adds an extra step which lets users filter their exports by any of the available options. Users can filter by basic properties like the annotator or the date annotated, but also by any available metadata properties configured for the selected task.

Selecting Export Destinations

Users can choose to export to their Innotescus account, or a selection of integrated cloud storage services

Local Exports

The default option for export destination is Innotescus. This option makes the export available for download on the exports tab of the current project, so a ny supervisor with access to the project can access it.

Cloud Exports

Innotescus allows users to generate exports directly in their linked cloud storage services, including Google Drive, Google Cloud, Amazon S3, and Dropbox. Once authenticated, users must select a destination within their cloud account where the export will be created; cloud providers with buckets require that a bucket is selected before the export can be generated.

Naming, Compressing, and Running Exports

Export Names

Users must designate a name for their export that does not include any commonly invalid characters like periods, question marks, quotes, and more.

Compressing Exports

While exports to the Innotescus account are compressed by default, exports to cloud storage accounts are not, and can be exported either compressed or uncompressed.

Password Protection

If compressing their export, users have the option to provide a password for the generated zip file, which must be supplied by anyone attempting to unzip it.

Annotation Formats

The table below summarizes the formats that are available for each task type.

  • ✅ Indicates a format/task type combination that is available for image annotation exports.
  • ✅ ✅ indicates a format/task type combination that is available for video annotation exports.
Coco (.json) .csv Innotescus .json Masks (.png) Pascal VOC (.xml) YOLO Darknet (.txt) YOLO Keras (.txt)
Classification
Object Detection ✅ ✅ ✅ ✅
Semantic Segmentation ✅ ✅ ✅ ✅ ✅ ✅
Instance Segmentation ✅ ✅ ✅ ✅ ✅ ✅

Coco (.json)

The Coco format is available for exporting any task aside from classification tasks. It is exported as a single .json file containing every annotation. Our coco annotation format is shown below:

info
{
    "description": str,
    "date_created": datetime
}

images
{
    "license": int,
    "file_name": str,
    "width": int,
    "height": int,
    "id": int
}

categories
{
    "supercategory": str,
    "id": int,
    "name": str
}

annotations
{
    "image_id": int,
    "id": int,
    "category_id": int,
    "segmentation": {"size":[image_height, image_width], "counts":[num_background_pixels, num_object_pixels, num_background, num_object...]}
    "area": int,
    "bbox": [x_upper_left,y_upper_left,width,height],
    "iscrowd": 0 or 1
}

Segmentation Run Length Encoding

Innotescus exports segmentations using run length encoding, or RLE. RLE encodes objects in a list of integers, each representing the number of pixelx that belong to the object or to the background, starting with background, going from top left to bottom right of the image. More information can be found on the coco website.

Coco Annotations on Video

For video annotations, the same format applies, only there will be one .json file per video in the annotated dataset. The image_id value now refers to the zero-indexed frame number of the corresponding video, and the id refers to an object's instance id within the video as a whole.

Coco + Metadata

The Coco + Metadata export format closely resembles the classic Coco format described above, but adds an attributes key to each image and annotation, which contains all the available metadata properties and populated values for each one. The modified Coco format to accommodate metadata is shown below:

info
{
    "description": str,
    "date_created": datetime
}

images
{
    "license": int,
    "file_name": str,
    "width": int,
    "height": int,
    "id": int,
    "attributes":
            {
                "image metadata property 1": value_1,
                "image metadata property 2": value_2,
                "image metadata property 3": value_3
            }
}

categories
{
    "supercategory": str,
    "id": int,
    "name": str
}

annotations
{
    "image_id": int,
    "id": int,
    "category_id": int,
    "segmentation": {"size":[image_height, image_width], "counts":[num_background_pixels, num_object_pixels, num_background, num_object...]}
    "area": int,
    "bbox": [x_upper_left,y_upper_left,width,height],
    "iscrowd": 0 or 1,
    "attributes":
        {
            "annotation metadata property 1": value_1,
            "annotation metadata property 2": value_2,
            "annotation metadata property 3": value_3
        }
}

Comma Separated Values (.csv)

The .csv format is available for all task types. Each line in the file represents a new annotation mask or classification, and follows the format below:

image name, width, height, task type, class, points, rotation(radians)

task type: Potential task type values are Classification, Object Detection, Semantic Segmentation, and Instance Segmentation.

points: For segmentations, this resembles "[x1, y1, x2, y2, x3, y3...]"; multi-polygon segmentations are given by a list of segmentaions, such as "[[xa1, ya1, xa2, ya2, xa3, ya3...],[xb1, yb1, xb2, yb2, xb3, yb3...]]" for a mask comprised of separate sub-masks a and b. For bounding boxes, this field contains x_min, y_min, x_max, y_max where (0, 0) is at the top left of the image. This field is empty for classification tasks.

Rotation (optional): This is measured in radians, and ranges from -π to π with respect to the positive x-axis. Rotation is only added for object detection tasks with bounding box rotation enabled.

If an object mask is comprised of multiple polygons, each polygon is enclosed in square brackets, and the list of polygons is enclosed in another pair of square brackets. Rotation, measured in radians, is only available when enabled in the task.

Innotescus .json

The Innotescus .json format is a proprietary .json format available for both image and video exports; it supports a broader set of information than a typical Coco .json file. Depending on the task and data types, the following files are included in the Innotescus .json export for each dataset that is exported:

classes.json
annotations.json
annotation_metadata_definitions.json
dataset_items.json
dataset_item_metadata_definitions.json

classes.json contains a list of class objects that conform to the format below:

{
    "id": int,
    "name": str,
    "parent_id": int
}

annotations.json contains a list of annotation objects that conform to the format below:

{
    "dataset_item_index": int,
    "frame_index": int,
    "type": "Box" | "Poly"
    "class_id": int,
    "instance_id": int,
    "box":
    {
        "x": int,
        "y": int,
        "w": int,
        "h": int,
        "orientation": null
    },
    "poly": [[{x1, y1}, {x2, y2}, ...][{x1, y1}, {x2, y2}, ...]],
    "is_open": bool,
    "annotators": str,
    "meta_data":
    {
        "metadata_property_1_name": metadata_property_1_value,
        "metadata_property_2_name": metadata_property_2_value,
        ...
    }
}
annotation_metadata_definitions.json contains a list of metadata definition objects that conform to the format shown below:
{
    "name": str,
    "display_name": str,
    "type": "Select" | "Int" | "Bool" | "String" | "Float",
    "required": bool,
    "classes":
    [
        "class_id_1",
        "class_id_2",
        ...
    ],
    "helpText": str,
    "default": str,
    "trueText": str,
    "min": min_val,
    "max": max_val,
    "options": //options for property type "List"
    [
        {
            "value": "value_1",
            "display_name": "optional_display_name_1"
        },                
        {
            "value": "value_2",
            "display_name": "optional_display_name_2"
        },
        ...
    ]
}
dataset_items.json contains a list of dataset item (images or videos) objects that conform to the format below:
{
    "index": int,
    "name": str,
    "num_frames": int,
    "width": int,
    "height": int,
    "url": str,
    "num_channels": int,
    "bits_per_channel": int,
    "meta_data":
    {
        "metadata_property_1_name": metadata_property_1_value,
        "metadata_property_2_name": metadata_property_2_value,
        ...
    }
}

dataset_item_metadata_definitions.json contains a list of metadata definition objects that conform to the format shown below:

"fields":
[
    {
        "name": str,
        "display_name": str,
        "type": "List" | "Int" | "Bool" | "String" | "Float",
        "required": bool,
        "classes":
        [],
        "helpText": str,
        "default": str,
        "trueText": str,
        "min": min_val,
        "max": max_val,
        "options": //options for property type "List"
        [
            {
                "value": str,
                "display_name": str
            },                
            {
                "value": str,
                "display_name": str
            },
            ...
        ]
    }

KITTI

The KITTI format is available for image annotation exports on object detection, instance, and semantic segmentation. The KITTI format is a simple .txt file format with one text file for each image, each containing one line for each annotated object in the image as shown below:

file: image_name.txt

class, truncated, occluded, alpha, bbox coordinates, dimensions, location, rotation
Where each item is defined as:

  • class: The class of the object
  • truncated: A float between 0 (not truncated) and 1 (truncated) describing the amount of the object that is outside the image boundaries
  • occluded: An integer representing occlusion state; possible values are 0 (fully visible), 1 (partly occluded), 2 (largely occluded), and 3 (unknown)
  • alpha: A float franging from -pi to pi, representing the observation angle of the object
  • bbox coordinates: Integer coordinates of the bounding box of the object, in the form [xmin ymin xmax ymax]
  • dimensions: Float values representing the height, width, length of the object
  • location: Float values representing the object's x, y, z coordinates relative to the camera
  • rotation: A float between -pi and pi representing rotation around the y-axis in camer coordinates

Mask (.png)

Mask exports are available only for semantic and instance segmentation tasks. There are three types of mask exports:

  • Aggregate Class Masks produce one bitmask for each image, with pixel values set to corresponding class values as defined in the classes.txt file in the exported zip file. Aggregate class masks are available for both semantic and instance segmentation tasks.
  • Individual Instance Masks create one bitmask per class (for semantic segmentation) or instance (for instance segmentation) in each image or video frame, so potentially multiple bitmasks per annotated image or frame; pixels with a value of 255 represent the instance, and filenames are constructed as imageName_className_instanceID for images and frameIndex_className_instanceID for videos. Individual class masks are available for both semantic and instance segmentation exports.
  • Aggregated Instance Masks include one bitmask for each image in the dataset, with pixel values set to distinguish between instances of the same class; each instance's class is defined in the classes.txt file. Instance masks are only available for instance segmentation tasks.

A 'classes.txt' file which maps pixel values to classes for each image is included in instance and aggregated class mask exports. The same information can be deduced from each file name in an individual class masks export. A sample 'classes.txt' file might look like the example below; every image name is followed by rows containing a pixel value followed by a class name, with a space in between:

Note: As long as all pixel values are less than or equal to 255, masks will default to a single channel, 8-bit .png file. If any pixel value must be greater than 255 (i.e. there are more than 255 instances in an instance mask, or a class' numerical ID is greater than 255), each .png file will be a single channel, 16-bit .png file.

Mask Annotations on Video

The mask annotation export for videos contains a single classes.txt file containing the pixel value to class mappings for every annotated video, and a folder for each annotated video containing a folder of masks and a folder of frames, correlated by filename. A sample folder structure is shown below:

classes.txt
/video_1_name
  /masks
    /0.png
    /1.png
    /2.png
    ⠇
  /frames
    /0.png
    /1.png
    /2.png
    ⠇
/video_2_name
⠇

Pascal VOC (.xml)

The Pascal format is available only for object detection tasks. This format exports a single .xml file for each image (each .xml file shares the name of the corresponding image), containing all of that image's objects, in the format shown below:

<annotation>
  <folder />
  <filename>image_name.jpg</filename>
  <source>
    <database> </database>
  </source>
  <size>
    <width>width</width>
    <height>height</height>
    <depth>depth</depth>
  </size>
  <segmented>0</segmented>
  <object>
    <name>class_name</name>
    <pose>N/A</pose>
    <truncated>0</truncated>
    <difficult>0</difficult>
    <bndbox>
      <xmin>x_min</xmin>
      <ymin>y_min</ymin>
      <xmax>x_max</xmax>
      <ymax>y_max</ymax>
    </bndbox>
  </object>
  <object>
    .
    .
    .
  </object>
</annotation>
<annotation>
    .
    .
    .
</annotation>
.
.
.

YOLO Darknet V4(.txt)

YOLO Darknet includes one .txt file for each image in a dataset, and one darknet.labels file. Each .txt file contains one line for each object in the corresponding image; each line has the format class_id x_center y_center width height, where each number is normalized (between 0 and 1). The class_id of an object corresponds to its zero-indexed row in the darknet.labels file. An example below shows a file containing annotations for an image with two humans:

two_humans.txt:
2 0.75 0.6666666 0.114 0.26266667
2 0.136 0.53066665 0.206 0.29333332
darknet.labels:
animal
human
food

YOLO Keras (.txt)

The YOLO Keras format includes two .txt files - yolokeras.annotations.txt and yolokeras.classes.txt. Like darknet.labels in the YOLO Darknet format, yolokeras.classes.txt includes a zero-indexed list of classes - one per line - and the row number of the class is the numeric ID of that class in the yolokeras.annotations.txt. The yolokeras.annotations.txt file references one image per line, with the format path/to/image.jpg box1 box2 ...boxN, where each box object conforms to the format x_min,y_min,x_max,y_max,class_id with no spaces in between each number. A sample of this format is shown below:

yolokeras.annotations.txt:
training/image1.png 25,72,105,130,3 95,150,48,76,3
training/image2.png 67,85,180,213,2 
yolokeras.classes.txt:
animal
human
food