Documentation
Search…
How-to guides
Python SDK quickstart
On the Segments.ai web platform you can create datasets, upload samples, create releases and download labels. All of these - and more - can also be done programmatically with the Python SDK.
This tutorial walks you through the most common Python SDK functions. The complete list of functions is documented in detail in the Python SDK reference.
First install the Segments.ai Python SDK using pip:
1
pip install --upgrade segments-ai
Copied!
Import the necessary packages, and initialize the Segments client using your API key:
1
from segments import SegmentsClient
2
import json
3
​
4
# You can find your api key at https://segments.ai/account
5
api_key = "YOUR_API_KEY_HERE"
6
​
7
client = SegmentsClient(api_key)
Copied!
Create a new dataset
Let's create a new image segmentation dataset programmatically using
client.add_dataset(). Note that this dataset will be created under the user account corresponding to the API key.1
name = "pets"
2
description = "A dataset with images of cats and dogs."
3
task_type = "segmentation-bitmap"
4
​
5
task_attributes = {
6
"format_version": "0.1",
7
"categories": [
8
{
9
"name": "cat",
10
"id": 1
11
},
12
{
13
"name": "dog",
14
"id": 2
15
},
16
{
17
"name": "other",
18
"id": 3
19
}
20
]
21
}
22
​
23
dataset = client.add_dataset(name, description, task_type, task_attributes)
24
print(json.dumps(dataset, indent=4))
Copied!
Add samples to a dataset
1
dataset = 'jane/pets' # a dataset is always referred to as user/dataset.
2
​
3
images = [
4
{
5
'name': 'Bombay_220.jpg',
6
'url': 'https://segmentsai-prod.s3.eu-west-2.amazonaws.com/assets/jane/a13358ef-a1ae-443c-8ea1-5f61dd9cdc26.jpg'
7
},
8
{
9
'name': 'shiba_inu_178.jpg',
10
'url': 'https://segmentsai-prod.s3.eu-west-2.amazonaws.com/assets/jane/4f47973f-5568-47f1-8a7d-44bfeb6f0f76.jpg'
11
},
12
{
13
'name': 'havanese_196.jpg',
14
'url': 'https://segmentsai-prod.s3.eu-west-2.amazonaws.com/assets/jane/2a6b3cd9-0688-422b-b555-8730d0813e1b.jpg'
15
}
16
]
17
​
18
for image in images:
19
name = image['name']
20
attributes = {
21
'image': {
22
'url': image['url']
23
}
24
}
25
sample = client.add_sample(dataset, name, attributes)
26
print(json.dumps(sample, indent=4))
Copied!
1
samples = client.get_samples(dataset)
2
print(json.dumps(samples, indent=4))
Copied!
Now switch to the Segments.ai web platform and label the three images you just uploaded by pressing the "Start labeling" button.
Get the label of a sample
Once you've labeled some samples, you can programmatically retrieve their labels using
client.get_label().1
dataset = 'jane/pets'
2
sample = client.get_samples(dataset)[0]
3
​
4
label = client.get_label(sample['uuid'], labelset='ground-truth')
5
print(json.dumps(label, indent=4))
Copied!
Optional: visualize the instance and semantic labels
When working with image segmentation datasets, you'll probably want to visualize the image and label at this point. The
segments.utils module offers some helper functions for that:1
import numpy as np
2
import matplotlib.pyplot as plt
3
from segments.utils import load_image_from_url, load_label_bitmap_from_url, get_semantic_bitmap
4
​
5
# Load the labels as numpy arrays
6
image = load_image_from_url(sample['attributes']['image']['url'])
7
instance_bitmap = load_label_bitmap_from_url(label['attributes']['segmentation_bitmap']['url'])
8
semantic_bitmap = get_semantic_bitmap(instance_bitmap, label['attributes']['annotations'])
9
​
10
# Visualize
11
plt.imshow(image)
12
plt.title('Image')
13
plt.show()
14
​
15
plt.imshow(instance_bitmap)
16
plt.title(f'Instance bitmap. Values represent instance ids: {np.unique(instance_bitmap)}')
17
plt.show()
18
​
19
plt.imshow(semantic_bitmap)
20
plt.title(f'Semantic bitmap. Values represent category ids: {np.unique(semantic_bitmap)}')
21
plt.show()
Copied!
What's next?
The Python SDK offers many more functions besides the ones that were shown here. Have a look at the reference for the full list.
The Python SDK can also be used to upload labels into Segments.ai. This is particularly useful for setting up model-assisted labeling workflows, where you verify and correct model predictions instead of labeling from scratch.
Last modified 2h ago