Registering new images or videos
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 your registration payload:
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.
For S3, exclude the 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"
.For Azure, include the container name, e.g. if the full path to your blob is
https://myaccount.blob.core.windows.net/mycontainer/myblob.jpg
then your key should be"mycontainer/myblob.jpg"
.
Video Streaming
If you have video streaming enabled then, currently, you have to use readwrite permissions for it to work.
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 2 months ago