Registering new images or videos

Suggest Edits

Images

After the external bucket is ready and you have populated it with images you need to notify Darwin which images Darwin should list, and for which dataset, this is done via a REST PUT request.

All REST endpoints in Darwin are using api keys for authentication, you can setup your own key here.

The following python scripts shows how to register a newly added image:

import requests

api_key = "your_key_here"

team_slug = "team_slug_here"
dataset_slug = "dataset_slug_here"
storage_name = "storage_name_here"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"ApiKey {api_key}"
}

payload = {
    "items": [
        {   
          "type": "image",
          "key": "darwin/cars/2008_000074.jpg",
          "filename": "2008_000074.jpg",
          # path field is optional but allows to reflect the same folder structure on Darwin 
          "path": "darwin/cars" 
        }
    ],
  "storage_name": storage_name
}

response = requests.put(
  f"https://darwin.v7labs.com/api/teams/{team_slug}/datasets/{dataset_slug}/data",
  headers=headers,
  json=payload
)

if response.status_code != 200:
    print("request failed", response.text)
else:
    print("success")

For more details, please refer to our API reference here.

Generating thumbnails

In cases where you prefer to generate thumbnails on your own, or when you are unable to give write access to V7 to your bucket, the payload changes slightly (notice thumbnail_key, width, height): 

"items": [
    {
        "type": "image",
        "key": "darwin/cars/2008_000074.jpg",
        "thumbnail_key": "darwin/2008_000074_thumbnail.jpg",
    "width": 1920,
    "height": 1080,
        "filename": "2008_000074.jpg"
    }
]

We recommend using mogrify for thumbnail generation.

> mogrify -resize "356x200>" -format jpg -quality 50 -write thumbnail.jpg large.png

❗️

Don't use original images as thumbnails

It is strongly recommended that you don't use the originally registered image for your thumbnail. This can lead to CORS issues on some browsers.

Videos

Videos in v7 consist of a single item record, with multiple corresponding frames. Each Frame provides the high quality image that is used to annotate against. If the external storage configurations allows V7 write access; the frames and thumbnails can be extracted by V7 automatically after registering the items. The example payload below is for read only external storage; which requires the frames to be pre-extracted.

payload = {
   "items":[
      {
         "type":"video",
         # The storage key where the file is stored.
         "key":"darwin/cars/video.mp4",
         # This is the display name of the video in the v7 web UI
         "filename":"car_video.mp4",
         # displayed when showing a thumbnail for the whole video (first frame is a reasonable option)
         # such as when listing all videos in a dataset
         "thumbnail_key":"darwin/cars/video-thumbnail.png",
         # Each video item consists of many frames 
         "frames":[
            {
                # the high quality frame which is displayed for annotation work when a video is paused
               "hq_key":"darwin/cars/frame_1_hq.png",
                # used during video playback
               "lq_key":"darwin/cars/frame_1_lq.png",
                # set to the same value as above `lq_key`
               "thumbnail_key":"darwin/cars/frame_1_lq.png",
               "width":480,
               "height":360
            },
            {
               "hq_key":"darwin/cars/frame_2_hq.png",
               "lq_key":"darwin/cars/frame_2_lq.png",
               "thumbnail_key":"darwin/cars/frame_2_lq.png",
               "width":480,
               "height":360

            },
                        {
               "hq_key":"darwin/cars/frame_3_hq.png",
               "lq_key":"darwin/cars/frame_3_lq.png",
               "thumbnail_key":"darwin/cars/frame_3_lq.png",
               "width":480,
               "height":360            }
         ]
      }
   ],
   "storage_name": storage_name
}

Notes on Read Only Access

If you enable read only access then you must add certain fields in the S3 bucket depending:

For Images: thumbnail_key, height and width for each image.

For Videos/DICOMs: thumbnail_key at the item level, hq_key (high quality frames used for annotation when the video is paused) and lq_key (low quality frames used during playback) as well as the height and width for each frame.

🚧

Tips on entering the key in your payload

The key should be the path where the file is stored, excluding your bucket name.

e.g. if the full path to your s3 bucket is s3://example-bucket/darwin/sub_folder/example_image.jpg then your key should be "darwin/sub_folder/example_image.jpg"

📘

Registering Multiple Items at once

It is possible to enter a list of items to be registered in one API query rather than making an API query for each individual item.

Updated 5 days ago