Private cloud integration

Videos

Each object in the videos array is a JSON object with the key objectUrl specifying the full URL of where to find the video resource. The title field is optional. If not specified, the video's file name will be used.

• Video metadata (separate from client metadata) may be specified for videos. Click here to read more.

• If skip_duplicate_urls is set to true, all object URLs that exactly match existing videos in the Dataset will be skipped.

ℹ️

Note

Keys / Flags that aren't required can be omitted from the JSON file entirely.

{
  "videos": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-custom-video-title.mp4",
      "clientMetadata": {"optional": "metadata"}
    }
  ],
  "skip_duplicate_urls": true
}

Video metadata

The JSON format allows you to specify videoMetadata for video files. videoMetadata is essential information used by the Label Editor and is crucial for aligning annotations to the correct frame.

❗️

CRITICAL INFORMATION

When 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 metadata you provide is accurate.

ℹ️

Note

videoMetadata must be specified when a Strict client-only access integration is used. In all other cases videoMetadata is optional.

Example JSON including video metadata

JSON

{
    "videos": [
      {
        "objectUrl": "video_file.mp4",
        "videoMetadata": {
            "fps": 23.98,
            "duration": 29.09,
            "width": 1280,
            "height": 720,
            "file_size": 5468354,
            "mime_type": "video/mp4"
        }
      }
    ]
  }

• fps: Frames per second.
• duration: Duration of the video (in seconds).
• width / height: Dimensions of the video (in pixels).
• file_size: The size of the file (in bytes).
• mime_type: Specifies the file type extension according to the MIME standard.

When videos are supplied with video metadata, Encord assumes the metadata to be correct and our servers will neither download nor pre-process your data. This may be a particularly useful feature for customers with strict data compliance concerns.

One way to find the necessary metadata is shown below. Run the following commands in your terminal.

• ffmpeg -i 'video_title.mp4' to retrieve fps, duration, width, and height - as highlighted below.

• ls -l 'video_title.mp4' to retrieve the file size - as highlighted below.

Single Images

The JSON structure for single images parallels that of videos.

• The title field is optional.
• If not specified, the file name of the image will be used.
• If skip_duplicate_urls is set to true, images that have been previously uploaded to the dataset with the same object URL will be skipped.
• Image metadata (separate from client metadata) may be specified for images. Click here to read more.

ℹ️

Note

Keys / Flags that are not required can be omitted from the JSON file entirely.

{
  "images": [
    {
      "objectUrl": "<object url>"
    },
    {
      "objectUrl": "<object url>",
      "title": "my-custom-image-title.jpeg",
      "clientMetadata": {"optional": "metadata"}
    }
  ]
}

Image metadata

The JSON format allows you to specify imageMetadata for image files. imageMetadata contains essential information used by the Label Editor and is crucial for aligning annotations to the correct image properties.

❗️

CRITICAL INFORMATION

When the imageMetadata 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.

ℹ️

Note

imageMetadata must be specified when a Strict client-only access integration is used. In all other cases, imageMetadata is optional.

{
  "images": [
    {
      "objectUrl": "s3://my_image.jpg",
      "imageMetadata": {
        "mimeType": "image/jpg",
        "fileSize": 124,
        "width": 640,
        "height": 480
      }
    }
  ]
}

• objectUrl: URL or path to the image file.
• mimeType: The MIME type of the image file (e.g., image/jpg, image/png).
• fileSize: The size of the image file in bytes.
• width: The width of the image in pixels.
• height: The height of the image in pixels.

Image groups

• 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.
• Custom client metadata is defined per image group, not per image.
• If skip_duplicate_urls is set to true, all URLs exactly matching existing image groups in the dataset will be skipped.

ℹ️

Note

The position of each image within the sequence needs to be specified in the key - e.g. objectUrl_{position_number} as seen in the example below.

ℹ️

Note

Keys / Flags that aren't required can be omitted from the JSON file entirely.

ℹ️

Note

Set the "createVideo" flag to false for image groups.

{
  "image_groups": [
    {
      "title": "<title 1>",
      "createVideo": false,
      "objectUrl_0": "<object url>"
    },
    {
      "title": "<title 2>",
      "createVideo": false,
      "objectUrl_0": "<object url>",
      "objectUrl_1": "<object url>",
      "objectUrl_2": "<object url>",
      "clientMetadata": {"optional": "metadata"}
    }
  ]
}

Image sequences

• 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 are 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.
• Custom client metadata is defined per image sequence, not per image.
• If skip_duplicate_urls is set to true, all URLs exactly matching existing image sequences in the Dataset are skipped.

👍

Tip

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

ℹ️

Note

The position of each image within the sequence needs to be specified in the key - e.g objectUrl_{position_number}. See the example below.

ℹ️

Note

Keys / Flags that are not required can be omitted from the JSON file entirely.

{
  "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>",
      "clientMetadata": {"optional": "metadata"}
    }
  ]
}

DICOM

ℹ️

Note

Ensure your DICOM files and metadata follow the format outlined in the official DICOM specification.

• Each dicom_series element can contain one or more DICOM series.
• Each file 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 are skipped.

ℹ️

Note

Keys / Flags that are not required, such as clientMetadata, can be omitted from the JSON file entirely. clientMetadata is distinct from patient metadata, which is included in the .dcm file and does not have to be specified 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.

{
  "dicom_series": [
    {
      "title": "<series-1>",
      "objectUrl_0": "https://my-bucket/.../study1-series1-file.dcm"
    },
    {
      "title": "<series-2>",
      "objectUrl_0": "https://my-bucket/.../study1-series2-file1.dcm",
      "objectUrl_1": "https://my-bucket/.../study1-series2-file2.dcm",
      "objectUrl_2": "https://my-bucket/.../study1-series2-file3.dcm",
    },
      {
      "title": "<series-3>",
      "objectUrl_0": "https://my-bucket/.../study1-series3-file1.dcm",
      "objectUrl_1": "https://my-bucket/.../study1-series3-file2.dcm",
    }
  ]
}

NIfTI

• Each series requires a title and at least one object URL.
• If skip_duplicate_urls is set to true, all object URLs exactly matching existing NIfTI files in the Dataset are skipped.

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

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

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.

ℹ️

Note

Keys / Flags that are not required can be omitted from the JSON file entirely.

{
  "images": [
    {
      "objectUrl": "https://cord-dev.s3.eu-west-2.amazonaws.com/Image1.png"
    }
  ],
  "videos": [
    {
      "objectUrl": "https://cord-dev.s3.eu-west-2.amazonaws.com/Cooking.mp4"
    },
    {
      "objectUrl": "https://cord-dev.s3.eu-west-2.amazonaws.com/Oranges.mp4"
    }
  ],
  "image_groups": [
    {
      "title": "apple-samsung-light",
      "createVideo": true,
      "objectUrl_0": "https://cord-dev.s3.eu-west-2.amazonaws.com/food-dataset/Apple/1-Samsung-S4-Light+Environment/1+(32).jpg",
      "objectUrl_1": "https://cord-dev.s3.eu-west-2.amazonaws.com/food-dataset/Apple/1-Samsung-S4-Light+Environment/1+(33).jpg",
      "objectUrl_2": "https://cord-dev.s3.eu-west-2.amazonaws.com/food-dataset/Apple/1-Samsung-S4-Light+Environment/1+(34).jpg",
      "objectUrl_3": "https://cord-dev.s3.eu-west-2.amazonaws.com/food-dataset/Apple/1-Samsung-S4-Light+Environment/1+(35).jpg"
    },
    {
      "title": "apple-samsung-dark",
      "createVideo": true,
      "objectUrl_0": "https://cord-dev.s3.eu-west-2.amazonaws.com/food-dataset/Apple/2-samsung-S4-Dark+Environment/2+(32).jpg",
      "objectUrl_1": "https://cord-dev.s3.eu-west-2.amazonaws.com/food-dataset/Apple/2-samsung-S4-Dark+Environment/2+(33).jpg",
      "objectUrl_2": "https://cord-dev.s3.eu-west-2.amazonaws.com/food-dataset/Apple/2-samsung-S4-Dark+Environment/2+(34).jpg",
      "objectUrl_3": "https://cord-dev.s3.eu-west-2.amazonaws.com/food-dataset/Apple/2-samsung-S4-Dark+Environment/2+(35).jpg"
    }
  ],
  "image_groups": [
    {
      "title": "apple-ios-light",
      "createVideo": false,
      "objectUrl_0": "https://cord-dev.s3.eu-west-2.amazonaws.com/food-dataset/Apple/3-IOS-4-Light+Environment/3+(32).jpg",
      "objectUrl_1": "https://cord-dev.s3.eu-west-2.amazonaws.com/food-dataset/Apple/3-IOS-4-Light+Environment/3+(33).jpg"
    }
  ]
}

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 are assigned the names in the title column, while file 3 keeps its original file name.

A CSV file containing single images MUST 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 following example files 1, 2 and 4 are assigned the names in the title column, while file 3 keeps its original file name.

Image groups

A CSV file containing image groups MUST 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 following example the first two URLs are grouped together into 'Group 1', while the following two files are grouped together into 'Group 2'.

ℹ️

Note

Image groups do not require 'write' permissions.

Image sequences

A CSV file containing image sequences MUST 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'.

👍

Tip

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

ℹ️

Note

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

A CSV file containing DICOM files MUST contain two columns with the following headings: 'ObjectURL' and 'Series title'. Both headings are case-insensitive.

• The 'ObjectURL' column contains the objectUrl. This field is mandatory for each file, as it specifies the full URL of the resource.

• The 'Series title' column contains 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 following example 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'.

A CSV file containing NIfTI files MUST contain two columns with the following headings: 'ObjectURL' and 'NIfTI title'. Both headings are case-insensitive.

• The 'ObjectURL' column contains the objectUrl. This field is mandatory for each file, as it specifies the full URL of the resource.

• The 'NIfTI title' column contains the title of the Nifti file. If left blank, the original file name is used.

The following example shows how to format the CSV file to upload two NIfTI files to Encord.

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.

🚧

Caution

Since the 'Create video' column defaults to "true" all files that aren't image sequences have to contain the value "false"

The following example 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.