Data Annotation

STEP 1: Import Your Files to Encord

Create a Cloud Integration

Select your cloud provider.

AWS Integration GCP Integration Azure Integration OTC Integration Wasabi Integration Oracle Integration Direct Access Integration

Create a Folder

You must create a folder in Index to store your files.

Navigate to Files under the Index heading in the Encord platform.
Click the + New folder button to create a new folder. Select the type of folder you want to create.

Give the folder a meaningful name and description.
Click Create to create the folder. The folder is listed in Files.

Create JSON or CSV for Registration

To register files from cloud storage with Encord, you must create a JSON or CSV file specifying the files you want to register.

Find helpful scripts for creating JSON and CSV files for the data registration process here.

All types of data (videos, images, image groups, image sequences, and DICOM) from a private cloud are added to a Dataset in the same way, by using a JSON or CSV file. The file includes links to all images, image groups, videos and DICOM files in your cloud storage.

For a list of supported file formats for each data type, go here

Encord supports file names up to 300 characters in length for any file or video for upload.

Encord enforces the following upload limits for each JSON file used for file registration:

Up to 1 million URLs
A maximum of 500,000 items (e.g. images, image groups, videos, DICOMs)
URLs can be up to 16 KB in size

Optimal upload chunking can vary depending on your data type and the amount of associated metadata. For tailored recommendations, contact Encord support. We recommend starting with smaller uploads and gradually increasing the size based on how quickly jobs are processed. Generally, smaller chunks result in faster data reflection within the platform.

BEST PRACTICE: If you want to use Index or Active with your video data, we STRONGLY RECOMMEND using custom metadata (clientMetadata) to specify key frames, custom metadata, and custom embeddings. For more information go here or here for information on using the SDK.

JSON Format

Create JSON file for Registration

For detailed information about the JSON file format used for import go here.The information provided about each of the following data types is designed to get you up and running as quickly as possible without going too deeply into the why or how. Look at the template for each data type, then the examples, and adjust the examples to suit your needs.

If skip_duplicate_urls is set to true, all object URLs that exactly match existing images/videos in the dataset are skipped.

JSON for AWS

AWS JSON

Videos

Video MetadataWhen the videoMetadata flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.

To guarantee accurate labels, it is crucial that the videoMetadata provided is accurate.

{
  "videos": [
    {
      "objectUrl": "cloud-path-to-your-video-1"
    },
    {
      "objectUrl": "cloud-path-to-your-video-2",
        "videoMetadata": {
          "fps": frames-per-second,
          "duration": duration-in-seconds,
          "width": frame-width,
          "height": frame-height,
          "file_size": file-size-in-bytes,
          "mime_type": "MIME-file-type-extension"
        }
      }
  ],
  "skip_duplicate_urls": true
}

Audio files

Audio Files

The following is an example JSON file for uploading two audio files to Encord.

Template: Imports audio files with an Encord title.
Audio Metadata: Imports one audio file with the audiometadata flag. When the audiometadata flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

{
  "audio": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-custom-audio-file-title.mp3"
    }
  ],
  "skip_duplicate_urls": true
}

PDFs

The following are example JSON files for uploading PDFs to Encord.

{
  "pdfs": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-document-02.pdf"
    },
    {
      "objectUrl": "<object url_3>",
      "title": "my-document-03.pdf",
      "pdfMetadata": {
        "fileSize": 300,
        "numPages": 5
        }
    }
  ],
  "skip_duplicate_urls": true
}

Text Files

The following are example JSON files for uploading text files to Encord.

{
  "text": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-file.html"
    },
    {
      "objectUrl": "<object url_3>",
      "title": "my-plain-text-file.txt",
      "textMetadata": {
        "fileSize": 200,
        "mime_type": "text/plain"
      }
    },
    {
      "objectUrl": "<object url_4>",
      "title": "my-csv-file.csv",
      "textMetadata": {
        "fileSize": 250,
        "mime_type": "text/csv"
      }
    },
    {
      "objectUrl": "<object url_5>",
      "title": "my-xml-file.xml",
      "textMetadata": {
        "fileSize": 300,
        "mime_type": "application/xml"
      }
    },
    {
      "objectUrl": "<object url_6>",
      "title": "my-html-file.html",
      "textMetadata": {
        "fileSize": 400,
        "mime_type": "text/html"
      }
    }
  ],
  "skip_duplicate_urls": true
}

Single images

Single Images

For detailed information about the JSON file format used for import go here.The JSON structure for single images parallels that of videos.Template: Provides the proper JSON format to import images into Encord.Examples:

Data Imports the images only.

{
  "images": [
    {
      "objectUrl": "file/path/to/images/file-name-01.file-extension"
    },
    {
      "objectUrl": "file/path/to/images/file-name-02.file-extension"
    },
    {
      "objectUrl": "file/path/to/images/file-name-03.file-extension",
      "title": "image-title.file-extension"
    }
  ],
  "skip_duplicate_urls": true
}

Image groups

For detailed information about the JSON file format used for import go here.

Image groups are collections of images that are processed as one annotation task.
Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
Image groups do NOT require ‘write’ permissions to your cloud storage.
If skip_duplicate_urls is set to true, all URLs exactly matching existing image groups in the dataset are skipped.

The position of each image within the sequence needs to be specified in the key (objectUrl_{position_number}).

Template: Provides the proper JSON format to import image groups into Encord.Examples:

Data: Imports the image groups only.

{
  "image_groups": [
    {
      "title": "<title 1>",
      "createVideo": false,
      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
    },
    {
      "title": "<title 2>",
      "createVideo": false,
      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
    }
  ],
  "skip_duplicate_urls": true
}

Image sequences

For detailed information about the JSON file format used for import go here.

Image sequences are collections of images that are processed as one annotation task and represented as a video.
Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
Creating Image sequences from cloud storage requires ‘write’ permissions, as new files have to be created in order to be read as a video.
Each object in the image_groups array with the createVideo flag set to true represents a single image sequence.
If skip_duplicate_urls is set to true, all URLs exactly matching existing image sequences in the dataset are skipped.

The only difference between adding image groups and image sequences using a JSON file is that image sequences require the createVideo flag to be set to true. Both use the key image_groups.

The position of each image within the sequence needs to be specified in the key (objectUrl_{position_number}).

Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.

Template: Provides the proper JSON format to import image groups into Encord.Examples:

Data: Imports the images groups only.

{
  "image_groups": [
    {
      "title": "<title 1>",
      "createVideo": true,
      "objectUrl_0": "<object url>"
    },
    {
      "title": "<title 2>",
      "createVideo": true,
      "objectUrl_0": "<object url>",
      "objectUrl_1": "<object url>",
      "objectUrl_2": "<object url>"
    }
  ],
  "skip_duplicate_urls": true
}

DICOM

For detailed information about the JSON file format used for import go here.

Each dicom_series element can contain one or more DICOM series.
Each series requires a title and at least one object URL, as shown in the example below.
If skip_duplicate_urls is set to true, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

Custom metadata is distinct from patient metadata, which is included in the .dcm file and does not have to be specific during the upload to Encord.

The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

The first series contains only a single object URL, as it is composed of a single file.
The second series contains 3 object URLs, as it is composed of three separate files.
The third series contains 2 object URLs, as it is composed of two separate files.

For each DICOM upload, an additional DicomSeries file is created. This file represents the series file-set. Only DicomSeries are displayed in the Encord application.

Template

{
  "dicom_series": [
    {
      "title": "Series-1",
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series1-file.dcm"
    },
    {
      "title": "Series-2",
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file1.dcm",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file2.dcm",
      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series2-file3.dcm",
    },
      {
      "title": "Series-3",
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file1.dcm",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/study1-series3-file2.dcm",
    }
  ],
  "skip_duplicate_urls": true
}

NIfTI

The following is an example JSON file for uploading two NIfTI files to Encord.

Template

{
    "nifti": [
      {
        "title": "<file-1>",
        "objectUrl": "https://my-bucket/.../nifti-file1.nii"
      },
      {
        "title": "<file-2>",
        "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
      }
    ],
    "skip_duplicate_urls": true
  }

Multiple file types

You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

Multiple file types

{
  "images": [
    {
      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/Image1.png"
    }
  ],
  "videos": [
    {
      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Cooking.mp4"
    },
    {
      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/videos/Oranges.mp4"
    }
  ],
  "image_groups": [
    {
      "title": "apple-samsung-light",
      "createVideo": true,
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(32).jpg",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
      "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
    },
    {
      "title": "apple-samsung-dark",
      "createVideo": true,
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(32).jpg",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(33).jpg",
      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(34).jpg",
      "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/2+(35).jpg"
    }
  ],
  "image_groups": [
    {
      "title": "apple-ios-light",
      "createVideo": false,
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(32).jpg",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/3+(33).jpg"
    }
  ],
  "skip_duplicate_urls": true
}

JSON for GCP

GCP JSON

Videos

To guarantee accurate labels, it is crucial that the videoMetadata provided is accurate.

{
  "videos": [
    {
      "objectUrl": "cloud-path-to-your-video-1"
    },
    {
      "objectUrl": "cloud-path-to-your-video-2",
        "videoMetadata": {
          "fps": frames-per-second,
          "duration": duration-in-seconds,
          "width": frame-width,
          "height": frame-height,
          "file_size": file-size-in-bytes,
          "mime_type": "MIME-file-type-extension"
        }
      }
  ],
  "skip_duplicate_urls": true
}

Audio files

Audio Files

The following is an example JSON file for uploading two audio files to Encord.

Example 1 imports audio files with an Encord title.
Example 2 imports one audio file with the audiometadata flag. When the audiometadata flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

{
  "audio": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-custom-audio-file-title.mp3"
    }
  ],
  "skip_duplicate_urls": true
}

PDFs

The following are example JSON files for uploading PDFs to Encord.

{
  "pdfs": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-document-02.pdf"
    },
    {
      "objectUrl": "<object url_3>",
      "title": "my-document-03.pdf",
      "pdfMetadata": {
        "fileSize": 300,
        "numPages": 5
        }
    }
  ],
  "skip_duplicate_urls": true
}

Text Files

The following are example JSON files for uploading text files to Encord.

{
  "text": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-file.html"
    },
    {
      "objectUrl": "<object url_3>",
      "title": "my-plain-text-file.txt",
      "textMetadata": {
        "fileSize": 200,
        "mime_type": "text/plain"
      }
    },
    {
      "objectUrl": "<object url_4>",
      "title": "my-csv-file.csv",
      "textMetadata": {
        "fileSize": 250,
        "mime_type": "text/csv"
      }
    },
    {
      "objectUrl": "<object url_5>",
      "title": "my-xml-file.xml",
      "textMetadata": {
        "fileSize": 300,
        "mime_type": "application/xml"
      }
    },
    {
      "objectUrl": "<object url_6>",
      "title": "my-html-file.html",
      "textMetadata": {
        "fileSize": 400,
        "mime_type": "text/html"
      }
    }
  ],
  "skip_duplicate_urls": true
}

Single images

Single Images

Data Imports the images only.
Image Metadata: Imports images with image metadata. This improves the import speed for your images.

{
  "images": [
    {
      "objectUrl": "file/path/to/images/file-name-01.file-extension"
    },
    {
      "objectUrl": "file/path/to/images/file-name-02.file-extension"
    },
    {
      "objectUrl": "file/path/to/images/file-name-03.file-extension",
      "title": "image-title.file-extension"
    }
  ],
  "skip_duplicate_urls": true
}

Image groups

For detailed information about the JSON file format used for import go here.

Image groups are collections of images that are processed as one annotation task.
Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
Image groups do NOT require ‘write’ permissions to your cloud storage.
If skip_duplicate_urls is set to true, all URLs exactly matching existing image groups in the dataset are skipped.

The position of each image within the sequence needs to be specified in the key (objectUrl_{position_number}).

Template: Provides the proper JSON format to import image groups into Encord.Examples:

Data: Imports the image groups only.

{
  "image_groups": [
    {
      "title": "<title 1>",
      "createVideo": false,
      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
    },
    {
      "title": "<title 2>",
      "createVideo": false,
      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
    }
  ],
  "skip_duplicate_urls": true
}

Image sequences

For detailed information about the JSON file format used for import go here.

Image sequences are collections of images that are processed as one annotation task and represented as a video.
Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
Creating Image sequences from cloud storage requires ‘write’ permissions, as new files have to be created in order to be read as a video.
Each object in the image_groups array with the createVideo flag set to true represents a single image sequence.
If skip_duplicate_urls is set to true, all URLs exactly matching existing image sequences in the dataset are skipped.

The only difference between adding image groups and image sequences using a JSON file is that image sequences require the createVideo flag to be set to true. Both use the key image_groups.

The position of each image within the sequence needs to be specified in the key (objectUrl_{position_number}).

Template: Provides the proper JSON format to import image groups into Encord.Examples:

Data: Imports the images groups only.

{
  "image_groups": [
    {
      "title": "<title 1>",
      "createVideo": true,
      "objectUrl_0": "<object url>"
    },
    {
      "title": "<title 2>",
      "createVideo": true,
      "objectUrl_0": "<object url>",
      "objectUrl_1": "<object url>",
      "objectUrl_2": "<object url>"
    }
  ],
  "skip_duplicate_urls": true
}

DICOM

For detailed information about the JSON file format used for import go here.

Each dicom_series element can contain one or more DICOM series.
Each series requires a title and at least one object URL, as shown in the example below.
If skip_duplicate_urls is set to true, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

Custom metadata is distinct from patient metadata, which is included in the .dcm file and does not have to be specific during the upload to Encord.

The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

The first series contains only a single object URL, as it is composed of a single file.
The second series contains 3 object URLs, as it is composed of three separate files.
The third series contains 2 object URLs, as it is composed of two separate files.

For each DICOM upload, an additional DicomSeries file is created. This file represents the series file-set. Only DicomSeries are displayed in the Encord application.

JSON for DICOM

{
  "dicom_series": [
    {
      "title": "Series-1",
      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series1-file.dcm"
    },
    {
      "title": "Series-2",
      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file1.dcm",
      "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file2.dcm",
      "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file3.dcm",
    },
      {
      "title": "Series-3",
      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file1.dcm",
      "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file2.dcm",
    }
  ],
  "skip_duplicate_urls": true
}

NIfTI

The following is an example JSON file for uploading two NIfTI files to Encord.

{
    "nifti": [
      {
        "title": "<file-1>",
        "objectUrl": "https://my-bucket/.../nifti-file1.nii"
      },
      {
        "title": "<file-2>",
        "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
      }
    ],
    "skip_duplicate_urls": true
  }

Multiple file types

You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

Multiple file types

{
  "images": [
    {
      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/Image1.png"
    }
  ],
  "videos": [
    {
      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Cooking.mp4"
    },
    {
      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Oranges.mp4"
    }
  ],
  "image_groups": [
    {
      "title": "apple-samsung-light",
      "createVideo": true,
      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/1+(32).jpg",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
      "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
    },
    {
      "title": "apple-samsung-dark",
      "createVideo": true,
      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/2+(32).jpg",
      "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/2+(33).jpg",
      "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/2+(34).jpg",
      "objectUrl_3": "https://storage.cloud.google.com/encord-image-bucket/images/2+(35).jpg"
    }
  ],
  "image_groups": [
    {
      "title": "apple-ios-light",
      "createVideo": false,
      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/3+(32).jpg",
      "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/3+(33).jpg"
    }
  ],
  "skip_duplicate_urls": true
}

JSON for Azure

Azure JSON

Videos

To guarantee accurate labels, it is crucial that the videoMetadata provided is accurate.

{
  "videos": [
    {
      "objectUrl": "cloud-path-to-your-video-1"
    },
    {
      "objectUrl": "cloud-path-to-your-video-2",
        "videoMetadata": {
          "fps": frames-per-second,
          "duration": duration-in-seconds,
          "width": frame-width,
          "height": frame-height,
          "file_size": file-size-in-bytes,
          "mime_type": "MIME-file-type-extension"
        }
      }
    {
      "objectUrl": "cloud-path-to-your-video-3",
      "title": "title-for-your-video-3"

    }
  ],
  "skip_duplicate_urls": true
}

Audio files

Audio Files

The following is an example JSON file for uploading two audio files to Encord.

Template: Imports audio files with an Encord title.
Audio Metadata: Imports one audio file with the audiometadata flag. When the audiometadata flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

{
  "audio": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-custom-audio-file-title.mp3"
    }
  ],
  "skip_duplicate_urls": true
}

PDFs

The following are example JSON files for uploading PDFs to Encord.

{
  "pdfs": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-document-02.pdf"
    },
    {
      "objectUrl": "<object url_3>",
      "title": "my-document-03.pdf",
      "pdfMetadata": {
        "fileSize": 300,
        "numPages": 5
        }
    }
  ],
  "skip_duplicate_urls": true
}

Text Files

The following are example JSON files for uploading text files to Encord.

{
  "text": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-file.html"
    },
    {
      "objectUrl": "<object url_3>",
      "title": "my-plain-text-file.txt",
      "textMetadata": {
        "fileSize": 200,
        "mime_type": "text/plain"
      }
    },
    {
      "objectUrl": "<object url_4>",
      "title": "my-csv-file.csv",
      "textMetadata": {
        "fileSize": 250,
        "mime_type": "text/csv"
      }
    },
    {
      "objectUrl": "<object url_5>",
      "title": "my-xml-file.xml",
      "textMetadata": {
        "fileSize": 300,
        "mime_type": "application/xml"
      }
    },
    {
      "objectUrl": "<object url_6>",
      "title": "my-html-file.html",
      "textMetadata": {
        "fileSize": 400,
        "mime_type": "text/html"
      }
    }
  ],
  "skip_duplicate_urls": true
}

Single images

Single Images

Data Imports the images only.
Image Metadata: Imports images with image metadata. This improves the import speed for your images.

{
  "images": [
    {
      "objectUrl": "file/path/to/images/file-name-01.file-extension"
    },
    {
      "objectUrl": "file/path/to/images/file-name-02.file-extension"
    },
    {
      "objectUrl": "file/path/to/images/file-name-03.file-extension",
      "title": "image-title.file-extension"
    }
  ],
  "skip_duplicate_urls": true
}

Image groups

For detailed information about the JSON file format used for import go here.

Image groups are collections of images that are processed as one annotation task.
Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
Image groups do NOT require ‘write’ permissions to your cloud storage.
If skip_duplicate_urls is set to true, all URLs exactly matching existing image groups in the dataset are skipped.

The position of each image within the sequence needs to be specified in the key (objectUrl_{position_number}).

Template: Provides the proper JSON format to import image groups into Encord.Examples:

Data: Imports the image groups only.

{
  "image_groups": [
    {
      "title": "<title 1>",
      "createVideo": false,
      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
    },
    {
      "title": "<title 2>",
      "createVideo": false,
      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
    }
  ],
  "skip_duplicate_urls": true
}

Image sequences

For detailed information about the JSON file format used for import go here.

Image sequences are collections of images that are processed as one annotation task and represented as a video.
Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
Creating Image sequences from cloud storage requires ‘write’ permissions, as new files have to be created in order to be read as a video.
Each object in the image_groups array with the createVideo flag set to true represents a single image sequence.
If skip_duplicate_urls is set to true, all URLs exactly matching existing image sequences in the dataset are skipped.

The only difference between adding image groups and image sequences using a JSON file is that image sequences require the createVideo flag to be set to true. Both use the key image_groups.

The position of each image within the sequence needs to be specified in the key (objectUrl_{position_number}).

Template: Provides the proper JSON format to import image groups into Encord.Examples:

Data: Imports the images groups only.

{
  "image_groups": [
    {
      "title": "<title 1>",
      "createVideo": true,
      "objectUrl_0": "<object url>"
    },
    {
      "title": "<title 2>",
      "createVideo": true,
      "objectUrl_0": "<object url>",
      "objectUrl_1": "<object url>",
      "objectUrl_2": "<object url>"
    }
  ],
  "skip_duplicate_urls": true
}

DICOM

For detailed information about the JSON file format used for import go here.

Each dicom_series element can contain one or more DICOM series.
Each series requires a title and at least one object URL, as shown in the example below.
If skip_duplicate_urls is set to true, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

Custom metadata is distinct from patient metadata, which is included in the .dcm file and does not have to be specific during the upload to Encord.

The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

The first series contains only a single object URL, as it is composed of a single file.
The second series contains 3 object URLs, as it is composed of three separate files.
The third series contains 2 object URLs, as it is composed of two separate files.

For each DICOM upload, an additional DicomSeries file is created. This file represents the series file-set. Only DicomSeries are displayed in the Encord application.

Template

{
  "dicom_series": [
    {
      "title": "Series-1",
      "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series1-file.dcm"
    },
    {
      "title": "Series-2",
      "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file1.dcm",
      "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file2.dcm",
      "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series2-file3.dcm",
    },
      {
      "title": "Series-3",
      "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series3-file1.dcm",
      "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/study1-series3-file2.dcm",
    }
  ],
  "skip_duplicate_urls": true
}

NIfTI

The following is an example JSON file for uploading two NIfTI files to Encord.

Template

{
    "nifti": [
      {
        "title": "<file-1>",
        "objectUrl": "https://my-bucket/.../nifti-file1.nii"
      },
      {
        "title": "<file-2>",
        "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
      }
    ],
    "skip_duplicate_urls": true
  }

Multiple file types

You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

{
  "images": [
    {
      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Image1.png"
    }
  ],
  "videos": [
    {
      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Cooking.mp4"
    },
    {
      "objectUrl": "https://myaccount.blob.core.windows.net/encordcontainer/Oranges.mp4"
    }
  ],
  "image_groups": [
    {
      "title": "apple-samsung-light",
      "createVideo": true,
      "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(32).jpg",
      "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(33).jpg",
      "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(34).jpg",
      "objectUrl_3": "https://myaccount.blob.core.windows.net/encordcontainer/1-Samsung-S4-Light+Environment/1+(35).jpg"
    },
    {
      "title": "apple-samsung-dark",
      "createVideo": true,
      "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(32).jpg",
      "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(33).jpg",
      "objectUrl_2": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(34).jpg",
      "objectUrl_3": "https://myaccount.blob.core.windows.net/encordcontainer/2-samsung-S4-Dark+Environment/2+(35).jpg"
    }
  ],
  "image_groups": [
    {
      "title": "apple-ios-light",
      "createVideo": false,
      "objectUrl_0": "https://myaccount.blob.core.windows.net/encordcontainer/3-IOS-4-Light+Environment/3+(32).jpg",
      "objectUrl_1": "https://myaccount.blob.core.windows.net/encordcontainer/3-IOS-4-Light+Environment/3+(33).jpg"
    }
  ],
  "skip_duplicate_urls": true
}

JSON for OTC

OTC JSON

Videos

To guarantee accurate labels, it is crucial that the videoMetadata provided is accurate.

{
  "videos": [
    {
      "objectUrl": "cloud-path-to-your-video-1"
    },
    {
      "objectUrl": "cloud-path-to-your-video-2",
        "videoMetadata": {
          "fps": frames-per-second,
          "duration": duration-in-seconds,
          "width": frame-width,
          "height": frame-height,
          "file_size": file-size-in-bytes,
          "mime_type": "MIME-file-type-extension"
        }
      }
  ],
  "skip_duplicate_urls": true
}

Audio files

Audio Files

The following is an example JSON file for uploading two audio files to Encord.

Template: Imports audio files with an Encord title.
Audio Metadata: Imports one audio file with the audiometadata flag. When the audiometadata flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.

{
  "audio": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-custom-audio-file-title.mp3"
    }
  ],
  "skip_duplicate_urls": true
}

PDFs

The following are example JSON files for uploading PDFs to Encord.

{
  "pdfs": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-document-02.pdf"
    },
    {
      "objectUrl": "<object url_3>",
      "title": "my-document-03.pdf",
      "pdfMetadata": {
        "fileSize": 300,
        "numPages": 5
        }
    }
  ],
  "skip_duplicate_urls": true
}

Text Files

The following are example JSON files for uploading text files to Encord.

{
  "text": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-file.html"
    },
    {
      "objectUrl": "<object url_3>",
      "title": "my-plain-text-file.txt",
      "textMetadata": {
        "fileSize": 200,
        "mime_type": "text/plain"
      }
    },
    {
      "objectUrl": "<object url_4>",
      "title": "my-csv-file.csv",
      "textMetadata": {
        "fileSize": 250,
        "mime_type": "text/csv"
      }
    },
    {
      "objectUrl": "<object url_5>",
      "title": "my-xml-file.xml",
      "textMetadata": {
        "fileSize": 300,
        "mime_type": "application/xml"
      }
    },
    {
      "objectUrl": "<object url_6>",
      "title": "my-html-file.html",
      "textMetadata": {
        "fileSize": 400,
        "mime_type": "text/html"
      }
    }
  ],
  "skip_duplicate_urls": true
}

Single images

Single Images

Data Imports the images only.
Image Metadata: Imports images with image metadata. This improves the import speed for your images.

{
  "images": [
    {
      "objectUrl": "file/path/to/images/file-name-01.file-extension"
    },
    {
      "objectUrl": "file/path/to/images/file-name-02.file-extension"
    },
    {
      "objectUrl": "file/path/to/images/file-name-03.file-extension",
      "title": "image-title.file-extension"
    }
  ],
  "skip_duplicate_urls": true
}

Image groups

For detailed information about the JSON file format used for import go here.

Image groups are collections of images that are processed as one annotation task.
Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
Image groups do NOT require ‘write’ permissions to your cloud storage.
If skip_duplicate_urls is set to true, all URLs exactly matching existing image groups in the dataset are skipped.

The position of each image within the sequence needs to be specified in the key (objectUrl_{position_number}).

Template: Provides the proper JSON format to import image groups into Encord.Examples:

Data: Imports the image groups only.

{
  "image_groups": [
    {
      "title": "<title 1>",
      "createVideo": false,
      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
    },
    {
      "title": "<title 2>",
      "createVideo": false,
      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
      "clientMetadata": {"optional": "metadata"}
    }
  ],
  "skip_duplicate_urls": true
}

Image sequences

For detailed information about the JSON file format used for import go here.

Image sequences are collections of images that are processed as one annotation task and represented as a video.
Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
Creating Image sequences from cloud storage requires ‘write’ permissions, as new files have to be created in order to be read as a video.
Each object in the image_groups array with the createVideo flag set to true represents a single image sequence.
If skip_duplicate_urls is set to true, all URLs exactly matching existing image sequences in the dataset are skipped.

The only difference between adding image groups and image sequences using a JSON file is that image sequences require the createVideo flag to be set to true. Both use the key image_groups.

The position of each image within the sequence needs to be specified in the key (objectUrl_{position_number}).

Template: Provides the proper JSON format to import image groups into Encord.Examples:

Data: Imports the images groups only.

{
  "image_groups": [
    {
      "title": "<title 1>",
      "createVideo": true,
      "objectUrl_0": "<object url>"
    },
    {
      "title": "<title 2>",
      "createVideo": true,
      "objectUrl_0": "<object url>",
      "objectUrl_1": "<object url>",
      "objectUrl_2": "<object url>"
    }
  ],
  "skip_duplicate_urls": true
}

DICOM

For detailed information about the JSON file format used for import go here.

Each dicom_series element can contain one or more DICOM series.
Each series requires a title and at least one object URL, as shown in the example below.
If skip_duplicate_urls is set to true, all object URLs exactly matching existing DICOM files in the dataset will be skipped.

Custom metadata is distinct from patient metadata, which is included in the .dcm file and does not have to be specific during the upload to Encord.

The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.

The first series contains only a single object URL, as it is composed of a single file.
The second series contains 3 object URLs, as it is composed of three separate files.
The third series contains 2 object URLs, as it is composed of two separate files.

For each DICOM upload, an additional DicomSeries file is created. This file represents the series file-set. Only DicomSeries are displayed in the Encord application.

JSON for DICOM

{
  "dicom_series": [
    {
      "title": "Series-1",
      "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series1-file.dcm"
    },
    {
      "title": "Series-2",
      "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file1.dcm",
      "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file2.dcm",
      "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series2-file3.dcm",
    },
      {
      "title": "Series-3",
      "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series3-file1.dcm",
      "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/study1-series3-file2.dcm",
    }
  ],
  "skip_duplicate_urls": true
}

NIfTI

The following is an example JSON file for uploading two NIfTI files to Encord.

{
    "nifti": [
      {
        "title": "<file-1>",
        "objectUrl": "https://my-bucket/.../nifti-file1.nii"
      },
      {
        "title": "<file-2>",
        "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
      }
    ],
    "skip_duplicate_urls": true
  }

Multiple file types

You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.

Multiple file types

{
  "images": [
    {
      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/Image1.png"
    }
  ],
  "videos": [
    {
      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/Cooking.mp4"
    },
    {
      "objectUrl": "https://encord-bucket.obs.eu-de.otc.t-systems.com/videos/Oranges.mp4"
    }
  ],
  "image_groups": [
    {
      "title": "apple-samsung-light",
      "createVideo": true,
      "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(32).jpg",
      "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(33).jpg",
      "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(34).jpg",
      "objectUrl_3": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/1+(35).jpg"
    },
    {
      "title": "apple-samsung-dark",
      "createVideo": true,
      "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(32).jpg",
      "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(33).jpg",
      "objectUrl_2": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(34).jpg",
      "objectUrl_3": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/2+(35).jpg"
    }
  ],
  "image_groups": [
    {
      "title": "apple-ios-light",
      "createVideo": false,
      "objectUrl_0": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/3+(32).jpg",
      "objectUrl_1": "https://encord-bucket.obs.eu-de.otc.t-systems.com/images/3+(33).jpg"
    }
  ],
  "skip_duplicate_urls": true
}

JSON for AWS Multi-Region Access Point

Use a Multi-Region Access Point

When using a Multi-Region Access Point for your AWS S3 buckets the JSON file has to be slightly different from the examples provided. Instead of an object’s URL, objects are specified using the ARN of the Multi-Region Access Point followed by the object name. The example below shows how video files from a Multi-Region Access Point would be specified.

{
  "videos": [
    {
      "objectUrl": "Multi-Region-Access-Point-ARN + <object name_1>"
    },
    {
      "objectUrl": "Multi-Region-Access-Point-ARN + <object name_2>",
      "title": "my-custom-video-title.mp4"
    }
  ],
  "skip_duplicate_urls": true
}

MRAP Example

{
  "videos": [
    {
      "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_1.mp4"
    },
    {
      "objectUrl": "https://arn:aws:s3::123123123:accesspoint/frf28frarf9.mrap.s3-accesspoint.amazonaws.com/Videos/2022/video_2.mp4",
      "title": "many-cute-cats.mp4"
    }
  ],
  "skip_duplicate_urls": true
}

CSV Format

Create CSV File for Registration

In the CSV file format, the column headers specify which type of data is being uploaded. You can add and single file format at a time, or combine multiple data types in a single CSV file.Details for each data format are given in the sections below.

Encord supports up to 10,000 entries for upload in the CSV file.

Object URLs can’t contain whitespace.
For backwards compatibility reasons, a single column CSV is supported. A file with the single ObjectUrl column is interpreted as a request for video upload. If your objects are of a different type (for example, images), this error displays: “Expected a video, got a file of type XXX”.

Videos

A CSV file containing videos should contain two columns with the following mandatory column headings:
‘ObjectURL’ and ‘Video title’. All headings are case-insensitive.

The ‘ObjectURL’ column containing the objectUrl. This field is mandatory for each file, as it specifies the full URL of the video resource.
The ‘Video title’ column containing the video_title. If left blank, the original file name is used.

In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

ObjectUrl	Video title
path/to/storage-location/frame1.mp4	Video 1
path/to/storage-location/frame2.mp4	Video 2
path/to/storage-location/frame3.mp4
path/to/storage-location/frame4.mp4	Video 3

Single images

A CSV file containing single images should contain two columns with the following mandatory headings:
‘ObjectURL’ and ‘Image title’. All headings are case-insensitive.

The ‘ObjectURL’ column containing the objectUrl. This field is mandatory for each file, as it specifies the full URL of the image resource.
The ‘Image title’ column containing the image_title. If left blank, the original file name is used.

In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.

ObjectUrl	Image title
path/to/storage-location/frame1.jpg	Image 1
path/to/storage-location/frame2.jpg	Image 2
path/to/storage-location/frame3.jpg
path/to/storage-location/frame4.jpg	Image 3

Image groups

A CSV file containing image groups should contain three columns with the following mandatory headings:
‘ObjectURL’, ‘Image group title’, and ‘Create video’. All three headings are case-insensitive.

The ‘ObjectURL’ column containing the objectUrl. This field is mandatory for each file, as it specifies the full URL of the resource.
The ‘Image group title’ column containing the image_group_title. This field is mandatory, as it determines which image group a file will be assigned to.

In the example below the first two URLs are grouped together into ‘Group 1’, while the following two files are grouped together into ‘Group 2’.

ObjectUrl	Image group title	Create video
path/to/storage-location/frame1.jpg	Group 1	false
path/to/storage-location/frame2.jpg	Group 1	false
path/to/storage-location/frame3.jpg	Group 2	false
path/to/storage-location/frame4.jpg	Group 2	false

Image groups do not require ‘write’ permissions.

Image sequences

A CSV file containing image sequences should contain three columns with the following mandatory headings: ‘ObjectURL’, ‘Image group title’, and ‘Create video’. All three headings are case-insensitive.

The ‘ObjectURL’ column containing the objectUrl. This field is mandatory for each file, as it specifies the full URL of the resource.
The ‘Image group title’ column containing the image_group_title. This field is mandatory, as it determines which image sequence a file will be assigned to. The dimensions of the image sequence are determined by the first file in the sequence.
The ‘Create video’ column. This can be left blank, as the default value is ‘true’.

In the example below the first two URLs are grouped together into ‘Sequence 1’, while the second two files are grouped together into ‘Sequence 2’.

ObjectUrl	Image group title	Create video
path/to/storage-location/frame1.jpg	Sequence 1	true
path/to/storage-location/frame2.jpg	Sequence 1	true
path/to/storage-location/frame3.jpg	Sequence 2	true
path/to/storage-location/frame4.jpg	Sequence 2	true

Image groups and image sequences are only distinguished by the presence of the ‘Create video’ column.

Image sequences require ‘write’ permissions against your storage bucket to save the compressed video.

DICOM

A CSV file containing DICOM files should contain two columns with the following mandatory headings: ‘ObjectURL’ and ‘Dicom title’. Both headings are case-insensitive.

The ‘ObjectURL’ column containing the objectUrl. This field is mandatory for each file, as it specifies the full URL of the resource.
The ‘Series title’ column containing the dicom_title. When two files are given the same title they are grouped into the same DICOM series. If left blank, the original file name is used.

In the example below the first two files are grouped into ‘dicom series 1’, the next two files are grouped into ‘dicom series 2’, while the final file will remain separated as ‘dicom series 3’.

ObjectUrl	Series title
path/to/storage-location/frame1.dcm	dicom series 1
path/to/storage-location/frame2.dcm	dicom series 1
path/to/storage-location/frame3.dcm	dicom series 2
path/to/storage-location/frame4.dcm	dicom series 2
path/to/storage-location/frame5.dcm	dicom series 3

Multiple file types

You can upload multiple file types with a single CSV file by using a new header each time there is a change of file type. Three headings will be required if image sequences are included.

Since the ‘Create video’ column defaults to true all files that are not image sequences must contain the value false

The example below shows a CSV file for the following:

Two image sequences composed of 2 files each.
One image group composed of 2 files.
One single image.
One video.

ObjectUrl	Image group title	Create video
path/to/storage-location/frame1.jpg	Sequence 1	true
path/to/storage-location/frame2.jpg	Sequence 1	true
path/to/storage-location/frame3.jpg	Sequence 2	true
path/to/storage-location/frame4.jpg	Sequence 2	true
path/to/storage-location/frame5.jpg	Group 1	false
path/to/storage-location/frame6.jpg	Group 1	false
ObjectUrl	Image title	Create video
path/to/storage-location/frame1.jpg	Image 1	false
ObjectUrl	Image title	Create video
full/storage/path/video.mp4	Video 1	false

Import your data

Import cloud data

Import Cloud Data

To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our limits and best practices for data import/registration before adding data to Encord.

Navigate to Files section of Index in the Encord platform.
Click into a Folder.
Click + Upload files. A dialog appears.

Click Import from cloud data.

We recommend turning on the Ignore individual file errors feature. This ensures that individual file errors do not lead to the whole upload process being aborted.

Click Add JSON or CSV files to add a JSON or CSV file specifying cloud data that is to be added.

Import local data

Import Local Data

Navigate to Files section of Index in the Encord platform.
Click into a Folder.
Click + Upload files. A dialog appears.

Click one of the following:
- Upload: Upload images, videos, and audio files.
- Batch images as: Upload image batches as image groups or image sequences.
- DICOM/NifTi: Upload DICOM or NifTi series.
Click Upload after selecting your images or series. Your files upload into the Folder in Encord.

STEP 2: Set Up Your Project

Create a Dataset

A Dataset is a subset of files that can be attached to one or more Projects for annotation.

Click the New dataset button in the Datasets section in Annotate.

Give your Dataset a meaningful title and description. A clear title and description keeps your data organized.

Toggle Looking to create a mirrored dataset? to create a Mirrored Dataset.

Click Create dataset to create the Dataset.

Attach files

You can add data to Datasets from the Files or the Datasets screens.

Navigate to the Datasets section under the Annotate heading.
Click the Dataset you want to attach data to.
Click +Attach existing files.

If the files you want have not been uploaded into Encord yet, click +Upload files to upload new files.

Select the folders containing the files you want to attach to the Dataset. To select individual files, double-click a folder to see its contents, and select the files you want to add to the Dataset.
Click Attach data to attach the selected files to the Dataset.

Create an Ontology

An Ontology is a structured framework that defines the categories, labels, and relationships used to annotate data consistently and accurately. Ontologies define what you want labeled.

We recommend learning about Ontology structure in Encord before creating Ontologies.

Click the New ontology button in the Ontologies section to create a new Ontology.

Give your Ontology a meaningful title and description. A clear title and description keeps your Ontologies organized.
Click Next to continue.

Define your Ontology structure. See our documentation on Ontology structure for more information on the various types of objects, classifications, and attributes.

To add objects:

Ensure that you add Audio Region objects for audio files and Text Region objects for text files.

Click Add object to create a new object.
Give the object a name. For example “Apple”.
Select a shape for the object. For example polygon.
Optionally, enable the Required toggle to mark the object as Required.
Optionally, add attributes to the object.
Repeat these steps for as many objects as necessary.

To add attributes to an object: You can add attributes to objects that define the object’s characteristics. For example the object “Apple” can have an attribute “Color”.

Click the arrow icon next to an object to add attributes to the object.
Give the attribute a name. For example “Color”.
Click the attribute type to change the attribute type. The default attribute type is a text field.
Click Add option to add an option, if you have chosen a radio button or checklist attribute.
Enter a name for the attribute option. For example, the attribute “Color” can have the options “Red”, “Green”, and “Yellow”.
Click the Back to parent button to return the Ontology creation view.

To add a classification:

Click Add classification to create a new classification.
Give the classification a name. For example, “Time of day”.
Optionally, configure the classification. The default classification type is a text field.
Optionally, enable the Required toggle to mark the object as Required.
Repeat these steps for as many classifications as necessary.

Configure classifications: You can configure classifications to change the classification type, and to add classification options to radio buttons and check lists.

Click the arrow icon next to an object to configure the classification.

Click the classification type to change the classification type. The default classification type is a text field.
Click Add option to add an option if you have selected a radio button or check list classification.
Enter a name for the classification option. For example, the classification “Time of day” can have the options “Night” and “Day”.
Click the Back to parent button to return the Ontology creation view.

Create a Task Agent

Task agents enable you to set up custom actions like pre-labeling, leveraging foundation models such as GPT-4, automated quality assurance, or other tailored actions to suit your workflow. Use the Encord SDK to configure your Task Agent. The Task Agent executes the configured SDK script for all tasks that are routed through the Task Agent stage in your Workflow.

General Example

The General Example script shows how to configure a Task Agent with the name Agent 1 and with a pathway called continue to Review.

Agent nodes can be used in conjunction with bundles to efficiently handle bulk actions

Ensure that you:

Replace <private_key_path> with the path to your private key.
Replace <project_hash> with the hash of your Project.
Insert your custom logic where the comment instructs you to do so.

General Example

# Import dependencies
from encord.user_client import EncordUserClient
from encord.workflow import AgentStage

# Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
ssh_private_key_path="<private_key_path>"
)

# Specify the Project that contains the Task agent. Replace <project_hash> with the hash of your Project
project = user_client.get_project(<project_hash>)

# Specify the Task Agent
agent_stage = project.workflow.get_stage(name="Agent 1", type_=AgentStage)
for task in agent_stage.get_tasks():

    # Now you have the agent task containing the data hash
    # Insert you custom logic here

# When the custom logic is completed, the task can be moved forward to the selected pathway
task.proceed(pathway_name="continue to Review")

Pre-Classification of Images Using GPT 4o

See our end-to-end guide for Pre-Classification using GPT 4o for more detailed information.

The Pre-Classification script uses GPT 4o mini to route images to different annotation stages depending on what it is contained in the image. The Pre-Classification script applies to the following Workflow.

Agent nodes can be used in conjunction with bundles to efficiently handle bulk actions

In the following script:

Replace <private_key_path> with the hash of your private key.
Replace <project_hash> with the hash of your Project.
Replace Agent 1 with the name of your Agent stage.

# Import dependencies
from encord.user_client import EncordUserClient
from encord.workflow import AgentStage
import openai
import base64
import requests
import json

# Initialize your OpenAI client
openai.api_key = "<your_openai_api_key>"

def get_classification_from_the_model(media_content):
    """
    Example function that passes media to OpenAI's ChatGPT API along with the prompt
    and parses the result.
    """
    prompt = """
    You are an image analysis expert. You're working on a project that includes annotation of different pets images.
    Your task is to assign one of the following tags to the image: "cat", "dog", "other".

    Reply in JSON format of the following structure: { "classification": cat|dog|other }
    """

    completion = openai.ChatCompletion.create(
        model="gpt-4o-mini",
        messages=[
            ChatCompletionSystemMessageParam(role="system", content=prompt),
            ChatCompletionUserMessageParam(
                role="user",
                content=[
                    ChatCompletionContentPartImageParam(
                        image_url=ImageURL(url=f"data:image/jpeg;base64,{media_content}", detail="auto"),
                        type="image_url",
                    )
                ]
            ),
        ],
        response_format=ResponseFormat(type="json_object"),
        max_tokens=1000,
    )

    raw_text_completion = completion.choices[0].message.content
    try:
        parsed_result = json.loads(raw_text_completion)
        return parsed_result["classification"].lower()
    except Exception as e:
        print(f"Failed to process the model response: {e}")
        return None


# Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Specify the Project that contains the Task agent. Replace <project_hash> with the hash of your Project
project = user_client.get_project("<project_hash>")

radio_classification = project.ontology_structure.get_child_by_title(
title="Animal",
type_=Classification,
)

cat_option = radio_ontology_classification.get_child_by_title(
title="Cat", type_=Option
)

dog_option = radio_ontology_classification.get_child_by_title(
title="Dog", type_=Option
)

# Specify the Task Agent
agent_stage = project.workflow.get_stage(name="Agent 1", type_=AgentStage)

for task in agent_stage.get_tasks():
    # Got a task for the following data unit
    print(f"{task.data_hash} -> {task.data_title}")

    # Getting a label row for the data unit
    label_row = project.list_label_rows_v2(data_hashes=[task.data_hash])[0]
    label_row.initialise_labels(include_signed_url=True)

    # Downloading the media:
    media_response = requests.get(label_row.data_link)
    media_content = base64.b64encode(media_response.content).decode("utf-8")

    # Now we can send the media to OpenAI:
    model_response = get_classification_from_the_model(media_content)

    # And interpret the result:
    match model_response:
        case "cat":

            # Create a classification instance
            classification_instance = (
                radio_ontology_classification.create_instance()
            )

            radio_classification_instance.set_answer(
                answer=cat_option
            )
            
            label_row.add_classification_instance(radio_classification_instance)
            label_row.save()

            task.proceed(pathway_name="Cat")
        case "dog":

            # Create & save classification instance
            classification_instance = (
                radio_ontology_classification.create_instance()
            )
        
            radio_classification_instance.set_answer(
                answer=dog_option
            )

            
            label_row.add_classification_instance(radio_classification_instance)
            label_row.save()

            task.proceed(pathway_name="Dog")
        case _:
            task.proceed(pathway_name="Other")

Pre-Labeling Videos Using a Mock Model

This guide makes the following assumptions:

You have a model that takes video frames as an input and provides bounding box coordinates and confidence scores as an output.
You have installed the encord-agents library using the following command:

python -m pip install encord-agents

The Pre-Labeling Script selects a random class from the Ontology, generates random bounding box labels, and applies random confidence scores for video frames before advancing the videos to the annotation stage (Annotate 1). Below is an example of a Workflow where the Pre-Labeling agent can be effectively utilized.

To authenticate, you must set either of following environment variables in the environment that you plan to run your agents.

ENCORD_SSH_KEY: Containing the raw private key file content
ENCORD_SSH_KEY_FILE: Containing the absolute path to the private key file

In the following script:

Replace <project_hash> with the hash of your Project.
Replace the mock model with your own model, and adapt the rest of the script according to your needs.
If you choose to give your python file a different name, ensure you replace all references to prelabel_video.py with your new file name.

prelabel_video.py

#Import Dependencies
import random
from dataclasses import dataclass
from typing import Iterable

import numpy as np
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.objects.ontology_labels_impl import LabelRowV2
from encord.project import Project
from encord_agents.core.data_model import Frame
from encord_agents.tasks import Depends, Runner
from encord_agents.tasks.dependencies import dep_video_iterator
from numpy.typing import NDArray
from typing_extensions import Annotated


# Set the Environment variable to authenticate with Encord
ENCORD_SSH_KEY_FILE="/path/to/file/" prelabel_video.py

runner = Runner(project_hash="<project_hash>")

# === BEGIN MOCK MODEL === #
@dataclass
class ModelPrediction:
    label: int
    coords: BoundingBoxCoordinates
    conf: float


def fake_predict(image: NDArray[np.uint8]) -> list[ModelPrediction]:
    return [
        ModelPrediction(
            label=random.choice(range(3)),
            coords=BoundingBoxCoordinates(
                top_left_x=random.random() * 0.5,
                top_left_y=random.random() * 0.5,
                width=random.random() * 0.5,
                height=random.random() * 0.5,
            ),
            conf=random.random() + 0.5,
        )
        for _ in range(10)
    ]


model = fake_predict
# === END MOCK MODEL === #

@runner.stage(stage="Pre-Labeling Agent")
def run_something(
    lr: LabelRowV2,
    project: Project,
    frames: Annotated[Iterable[Frame], Depends(dep_video_iterator)],
) -> str:
    ontology = project.ontology_structure

    # Create an object instance for each frame in the video and save the labels. 
    for frame in frames:
        outputs = model(frame.content)
        for output in outputs:
            ins = ontology.objects[output.label].create_instance()
            ins.set_for_frames(
                frames=frame.frame, coordinates=output.coords, confidence=output.conf
            )

            lr.add_object_instance(ins)

    lr.save()

    # Return the name of the stage the task should progress to
    return "Annotate 1"  


if __name__ == "__main__":
    runner.run()

Triggering the Task Agent

Webhooks are coming soon, allowing you to trigger Task Agents manually.

Task Agents aggregate all tasks that reach the Agent stage in the workflow. Your custom script must be triggered at this stage before the tasks proceed further in the workflow.

Create a Workflow

Workflows allow you to design and manage the flow of tasks through various stages of a Project. You have control over how tasks progress and how different stages interact.

Video tutorial - Creating workflow templates

To set up a Workflow template, navigate to the Project section of the Encord platform and select the Templates tab.

1. Add users to the Workflow: Add users from your Organization to the Workflow by clicking Invite collaborators.

Collaborators are added based on their role within the project - select the role you would like the collaborator(s) to have.
Start typing the email of a user you would like to add into the area highlighted on the image below, and select the user from the list that appears. Repeat this for every user that will have the same role.
When you are done selecting users for this role, click Add.

Learn more about managing collaborators in the Managing collaborators section.

2. Configure your Workflow: The canvas is populated with a simple Workflow by default. Click the Add stage button to show all Workflow components.

Customize your Workflow by pulling components onto the canvas.

Add the stages and other components you require for your Workflow onto the canvas:

All workflows must begin with the Start stage.
All workflows must contain an Annotate stage.
Add routers to your Project to determine different pathways through your Workflow a task can take.
Add as many Review stages as necessary.
All workflows must end at a Complete stage.
Link all components on the canvas by clicking and dragging from one connection point to another.

All Workflows can be saved as a template by clicking the Save as a new template button.

3. Configure the stages of your Workflow: After you arranged the stages in the composer, it is time to configure the details of each stage.

Click an Annotate card on the canvas to start editing the annotation stage.
- Give the stage a descriptive name.
- Add annotators. If you’d like to specify annotators for this stage, add them as collaborators. For full details on how collaborators can work on tasks at each stage, see our section on managing collaborators.
- Optionally, add a Webhook to receive notifications when labels are submitted at this stage.

More details about configuring annotation stages can be found in the Annotate section below

Click a Review card on the canvas to start editing the review stage.
- Give the stage a descriptive name.
- Add reviewers. If you want to specify reviewers for this stage, add them as collaborators. For full details on how collaborators can work on tasks at each stage, see our section on managing collaborators.

More details about configuring review stages can be found in the Review section below.

Click a Router card on your canvas. See the router section for more details on how different types of routers can be configured.
Optionally, add a Webhook to the Complete stage to receive a notification when a task has been completed.
Optionally, add User assignment restrictions if users in this node should be prevented from being assigned to tasks they completed in the nodes listed.

More details on routers can be found in the router section below.

Create a Project

Projects in Encord bring together Datasets, Ontologies, and Workflows. Datasets are labeled according to the Ontology, while the Workflow defines how tasks progress through the Project from start to finish.

In the Encord platform, select Projects under Annotate.
Click the + New annotation project button to create a new Project.

Give the Project a meaningful title and description.

If you are part of an Organization, an optional Project tags drop-down is visible. Project tags are useful for categorizing and finding your Projects. Select as many tags as are relevant for your Project.

Click the Attach ontology button.
Select an Ontology from the list using the Select button, or create a new Ontology by clicking the New ontology button.

Click OK to attach the Ontology to the Project.
Click the Attach datasets button.
Select a Dataset from the list using the Attach button, or create a new Dataset by clicking the New Dataset button.

Click OK to attach the Dataset(s) to the Project.

Click the Load from template button to use a Workflow template.

Select the template you want to use and click Load template.
Click Create project to finish creating the Project.

Add users to the Project

After creating a Project, invite users to act as annotators, reviewers, team managers, and admins. Collaborators can be added as individuals, or as part of user groups.

Invite individuals

Navigate to Projects in the Encord app.

Select the Project you want to add users to.
Navigate to the Settings tab.
Navigate to the Team pane.
Click Invite collaborators.

Select the desired role for the users.
Enter the users’ email addresses and choose the users to assign the selected role.
Click Add to include the selected users in the Project.

Repeat this process for each required user role.

Invite user groups

To invite user groups your Organization must have user groups.

Navigate to Projects in the Encord app.

Select the Project you want to add users to.
Navigate to the Settings tab.
Navigate to the Team pane.
Select the Groups tab.
Click Manage.

Select a group from the dropdown.
Select the role you want the user group to have.
Click Add to add the user group to the Project.

Repeat this process for each required user group and role.

STEP 3: Label your Data

Now you are ready to label your data. We recommend you and your team watch these introductory videos.

For more details, see our comprehensive tutorial on labeling here.

Video tutorial - Introduction to image annotation

Video tutorial - Introduction to video annotation

STEP 4: Export your Labels

Only Project admins can export labels

Descriptions of all information contained in the export file can be found in the export file reference.

Click Export while in a Project. The Export labels dialog appears.
Specify the following:
- Format: Specify the format to export the labels (JSON or COCO).
- Stage: Specify the Workflow stage to export the labels from.
- Generate signed URLs: Specify whether to generate signed URLs for the data units that have labels.
Enabling this option can significantly increase export times.
- Save as new version: Specify to version the labels.
  - Provide a meaningful name for the label version.
- Labels to include: Specify the labels to include. You can export all labels or select specific object or classification labels to export.
Click Export. A Labels export in progress toast message appears.

Legacy

Navigate to Labels and export on the Project Dashboard
Select the Data tab.
Select the data units you want to export labels for.
Click the Export and save button. A pop-up appears.

Give this label version a name.
Select whether you want your labels to be exported in JSON or COCO format.
Toggle this if you want to include signed URLs in your export.
Select which label status(es) to include in the export.
Select what objects to include in the export.
Specify the label batching strategy.
Click Export and save to export your labels.

Get Started

General

Index

Annotate

Active

Other

​STEP 1: Import Your Files to Encord

​Create a Cloud Integration

​Create a Folder

​Create JSON or CSV for Registration

​Create JSON file for Registration

​AWS JSON

​GCP JSON

​Azure JSON

​OTC JSON

​Use a Multi-Region Access Point

​Create CSV File for Registration

​Videos

​Image groups

​Image sequences

​Multiple file types

​Import your data

​Import Cloud Data

​Import Local Data

​STEP 2: Set Up Your Project

​Create a Dataset

​Attach files

​Create an Ontology

​Create a Task Agent

​Triggering the Task Agent

​Create a Workflow

​Create a Project

​Add users to the Project

​STEP 3: Label your Data

​STEP 4: Export your Labels

​Recommended

​Legacy

STEP 1: Import Your Files to Encord

Create a Cloud Integration

Create a Folder

Create JSON or CSV for Registration

Create JSON file for Registration

AWS JSON

GCP JSON

Azure JSON

OTC JSON

Use a Multi-Region Access Point

Create CSV File for Registration

Videos

Image groups

Image sequences

Multiple file types

Import your data

Import Cloud Data

Import Local Data

STEP 2: Set Up Your Project

Create a Dataset

Attach files

Create an Ontology

Create a Task Agent

Triggering the Task Agent

Create a Workflow

Create a Project

Add users to the Project

STEP 3: Label your Data

STEP 4: Export your Labels

Recommended

Legacy