Python SDK

The Python SDK is a convenient wrapper for the API.

Setup

Please refer to this blog post for a full example of working with the Python SDK.

First install the SDK.

pip install segments-ai --upgrade

Import the segments package in your python file and and set up a client with an API key. An API key can be created on your user account page.

from segments import SegmentsClient
api_key = "eabdde840de8c8853329c086bc4165591cb3d74c"
client = SegmentsClient(api_key)

Datasets

List datasets

user = "jane"
datasets = client.get_datasets(user)
for dataset in datasets:
print(dataset["name"], dataset["description"])

Get a dataset

dataset_identifier = "jane/flowers"
dataset = client.get_dataset(dataset_identifier)
print(dataset)

Create a dataset

dataset_name = "flowers"
description = "A dataset containing flowers of all kinds."
category = "garden"
dataset = client.add_dataset(dataset_name, description, category)
print(sample)

Delete a dataset

dataset_identifier = "jane/flowers"
client.delete_dataset(dataset_identifier)

Samples

List samples

dataset = "jane/flowers"
samples = client.get_samples(dataset)
for sample in samples:
print(sample["name"], sample["uuid"])

Get a sample

sample = client.get_sample(uuid="602a3eec-a61c-4a77-9fcc-3037ce5e9606")
print(sample)

Create a sample

dataset = "jane/flowers"
name = "violet.jpg"
attributes = {
"image": {
"url": "https://example.com/violet.jpg"
}
}
sample = client.add_sample(dataset, name, attributes)
print(sample)

If the image is on your local computer, you should first upload it to a cloud storage service like Amazon S3, Google Cloud Storage, Imgur, or our asset storage service.

If you create a sample with a URL from a public S3 bucket and you see an error on the platform, make sure to properly configure your bucket's CORS settings.

Delete a sample

client.delete_sample(uuid="602a3eec-a61c-4a77-9fcc-3037ce5e9606")

Labels

Get a label

sample_uuid = "602a3eec-a61c-4a77-9fcc-3037ce5e9606"
task = "segmentation"
label = client.get_label(sample_uuid, task)
print(label)

Create or update a label

A label can be added to a sample in relation to a task defined on the dataset, such as an image classification task or an image segmentation task.

The task specifies the format that is required for the label: for a classification task, the attributesfield should contain different fields than for a segmentation task.

sample_uuid = "602a3eec-a61c-4a77-9fcc-3037ce5e9606"
task_name = "segmentation"
attributes = {
"segmentation_bitmap": {
"url": "https://segmentsai-prod.s3.eu-west-2.amazonaws.com/assets/bert/49f6aa10-8967-4305-985c-cdc1e8f89b93.png"
},
"annotations": [
{
"id": 1,
"category_id": 2
},
{
"id": 2,
"category_id": 3
}
]
}
client.add_label(sample_uuid, task_name, attributes)

Thesegmentation_bitmap_urlrefers to a 32-bit RGBA png image. The alpha channel is set to 255, and the remaining 24-bit values in the RGB channels correspond toinstance_ids.

The easiest way to transform a segmentation bitmap into this format and upload it is by using the util functionbitmap2file:

from segments.utils import bitmap2file
# segmentation_bitmap is a numpy array of type np.uint32, with values corresponding to instance_ids
file = bitmap2file(segmentation_bitmap)
asset = client.upload_asset(file, "label.png")
segmentation_bitmap_url = asset["url"]

For a full example of uploading model-generated labels to Segments.ai, please refer to this blogpost.

Delete a label

sample_uuid = "602a3eec-a61c-4a77-9fcc-3037ce5e9606"
task_name = "segmentation"
client.delete_label(sample_uuid, task)

Upload a file as an asset

Example with an image:

filename = "/home/jane/flowers/violet.jpg"
with open(filename, "rb") as f:
asset = client.upload_asset(f, filename="violet.jpg")
image_url = asset["url"]