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

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
}