SDK Cheat Sheet

A quick reference guide for common operations in the Dataloop SDK — including Projects, Datasets, Items, Recipes, Annotations, Tasks, and more.

Projects

Manage your Dataloop projects — create, list, and manage members.

# Create a project
project = dl.projects.create(project_name='my-new-project')

# Print projects list
dl.projects.list().print()

# Open project on the web
project.open_in_web()

# Get projects list
dl.projects.list()

# Get a project by name
project = dl.projects.get(project_name='my-project')

# Get a project by ID
project = dl.projects.get(project_id='my-project-id')

# Add project users ID
project.add_member(email='email@email.com', role=dl.MEMBER_ROLE_DEVELOPER)

# List project users ID
members_list = project.list_members(role=dl.MemberRole.ANNOTATOR)

# Remove project users ID
project.remove_member(email='email@email.com')

More about projects SDK on Project.

Datasets

Manage and access datasets within a project.

# Create a dataset
dataset = project.datasets.create(dataset_name='my-dataset-name')

# Print dataset
dataset.print()

# Open datasets on the web
dataset.open_in_web()

# Get a projects datasets list
datasets = project.datasets.list()

# Get the datasets by name
dataset = project.datasets.get(dataset_name='my-dataset-name')

# Get the datasets by ID
dataset = project.datasets.get(dataset_id='my-dataset-id')

More about datasets SDK on Datasets.

Items

Upload, download, clone, and manage dataset items.

# Upload items
dataset.items.upload(local_path="/path/to/image.jpg")

# Upload items to a specific folder
dataset.items.upload(local_path="/path/to/image.jpg",remote_path="/path/to/dataset/folder")

# Download items
item.download(local_path="/where/to/save")

# Download items from a specific folder
item.download(local_path="/where/to/save",remote_path="/from/where/to/download")

# Open item on the web
item.open_in_web()

# Clone Items
item.clone(dst_dataset_id='your-dataset-id-number', with_annotations=True, with_metadata=True, with_task_annotations_status=False)

# Get-item-by-ID
item = dataset.items.get (item_id = 'my_item_Id')

More about Items SDK is available in the Items section.

Metadata

Add and update custom metadata for items.

Add-metadata

item.metadata [ 'user' ] = dict ()
item.metadata [ 'user'][ 'MyKey' ] = 'MyValue'
item.update()

Recipe And Ontology

Manage dataset labels, recipes, and ontologies.

# Add a label
dataset.add_label(label_name='person', color=(34, 6, 231), attributes=['big', 'small'])

# Delete labels
dataset.delete_labels(label_names=['myLabel1', 'Mylabel2'])

# Copy datasets ontology to a new dataset
new_dataset = project.datasets.create(dataset_name='new_dataset_with_ontology',ontology_ids=dataset.ontology_ids)

# Create a new recipe
recipe = dataset.recipes.create(recipe_name='My Recipe', labels=labels))

# Update recipe changes
recipe.update()

# Delete recipe (For deleted datasets)
dataset.recipes.get(recipe_id='my_recipe_id').delete())

# Get the recipe by ID
recipe = dataset.recipes.get(recipe_id='my_recipe_id')

# Get ontology by ID
ontology= recipe.ontologies.get(ontology_id='my_ontology_id')

# Get child label
childLabel = ontology.labels[x].children[y].children[z]

# Change the annotation label to a different label:
annotation.label = "label2"
annotation.update()

For more information, read the SDK-Docs for Recipe and Ontology entities.

Annotations

Upload, update, and create annotations.

# Upload annotations
annotations =   item.annotations.upload(annotations=local_annotation_path) 

# Update annotation changes
annotation = annotation.update() 

# Create annotation builder
builder = item.annotations.builder()   

# Add box annotation with label person
builder.add(annotation_definition=dl.Box(top=10,left=10,bottom=100, right=100,label='labelName')) 
item.annotations.upload(builder)

# Add annotations of type segmentation
builder.add(annotation_definition=dl.Segmentation(geo=mask,label='label1'))

# Add polyline annotation with label person
builder.add(annotation_definition=dl.Polyline(geo=[[80, 40],[100, 120],[110, 130]], label='person'))

# Create a mask for semantic segmentation
mask = np.zeros(shape=(item.height, item.width), dtype=np.uint8)
mask[50:100, 200:250] =

For more information, read the SDK-Docs about the Annotation entity.

Filters

Use filters to query items or resources.

# Initiate Filter
filter = dl.Filters()

# Filter only files:
filter.add(field='type', values='file')

# Filter only annotated items:
filter.add(field='annotated', values=True)

# Filter items by name that includes 'dog'
filter.add(field='name', values='dog')

# Filter items by name or directory that includes 'dog'
filter.add(field='filename', values='dog')

# Filter specific directory:
filter.add(field='dir', values='/myDirectory')

# Filter directory items with all subdirectories
filter.add('dir', '/myDirectory/*', method='or')

# Update filtered items (bulk update)
pages = dataset.items.update(filters=filter, update_values=update_values)

# Delete filtered items (bulk delete)
dataset.items.delete(filters=filter)

# Get filtered items list:
items_list = dataset.items.list(filters=filter)

# Filter all items with the annotation type - Box
filters.resource = 'items'
filters.add(field='type', values='file')
filters.add_join(field='type', values='box')
list = dataset.items.list(filters=filters)

For more information, read the SDK docs for the Filter entity details or the Sort-and-Filter tutorial.

Task and Assignments

Manage labeling workflows and user assignments. To learn more about Dataloop's tasks and assignments, see Tasks & Assignments.

Some tasks & assignments commands might require importing the datetime.

import datetime

Tasks

Manage labeling tasks.

# Create a task
task = dataset.tasks.create(
   task_name= 'task_name', 
   due_date = datetime.datetime(day= 1, month= 1, year= 2029).timestamp(),
   assignee_ids =[ 'annotator1@dataloop.ai', 'annotator2@dataloop.ai'])

# Create QA task
task.create_qa_task(
due_date=datetime.datetime(day= 1, month= 1, year= 2029).timestamp(),
assignee_ids=[ 'annotator1@dataloop.ai', 'annotator2@dataloop.ai'])

# Add items to the task:
filters = dl.Filters( field= 'dir', values= '/my/folder/directory')
task.add_items(
filters=filters, assignee_ids=[ 'annotator1@dataloop.ai', 'annotator2@dataloop.ai'])

# Delete a task
task.delete()

# This example shows how to set a single item to status COMPLETED
# Single status update
item = dataset.items.get (item_id=<itemId>);
task = dataset.tasks.get (task_name=<"task_name">);
item.update_status(status=dl.ItemStatus.COMPLETED, task_id=task.id);

# Status can be set to COMPLETED/APPROVE/DISCARD or other statuses that were created as actions on a task by the task creator.

# Get task
project.tasks.get(task_id= 'my-Task-Id') 

# Get task items
items_list= task.get_items()

# Get tasks list
task_list = project.tasks.list()

Assignments

Manage user assignments.

# Remove items from assignments
assignment. remove_items( filters= filter)

# Redistribute assignments
assignment.redistribute(dl.Workload([dl.WorkloadUnit(assignee_id="annotator1@dataloop.ai", load=50), dl.WorkloadUnit(assignee_id="annotator2@dataloop.ai", load=50)]))
  
# Reassign assignment
assignment.reassign(assignee_ids['annotator1@dataloop.ai'])

# Get assignment
task.assignments.get(assignment_id= 'my_assignment_Id')

# Get assignment items
items_list= assignment.get_items()

# Get the assignment list of a task
task.assignments.list()

# Get an assignments list of a project
project.assignments.list()

For more information, read the SDK Docs for details of the Tasks and Assignment repositories.

Applications

Handle modalities, similarities, and multi-view data.

# Create a modality
item1 = dataset.items.get(item_id='my_item_Id')
item2 = dataset.items.get(item_id='my_2_item_Id')
item1.modalities.create(name='my modality', modality_type=dl.ModalityTypeEnum.OVERLAY, ref=item2.id)
item1.update()

# Create a similarity
target_item = dataset.items.get(filepath='/remote/path/target_item.png')
ref_item1 = dataset.items.get(filepath='/remote/path/product1.jpeg')
ref_item2 = dataset.items.get(filepath='/remote/path/product2.jpeg')
ref_item3 = dataset.items.get(filepath='/remote/path/product3.jpeg')
similarity = dl.Similarity(name='my-product-similarity', ref=target_item.id, items=[ref_item1, ref_item2, ref_item3])
dataset.items.upload(local_path=similarity, remote_path='/products_similarities')

# Create a multi-view
item = dataset.items.get(filepath='/remote/path/original_item.png')
item2 = dataset.items.get(filepath='/remote/path/second_item.png')
multiview = dl.MultiView(name='my-items-multiview', items=[item, item2])
dataset.items.upload(local_path=multiview, remote_path='/remote/path'

FaaS

Deploy and manage serverless functions in Dataloop. To learn more about Dataloop's FaaS, see FaaS (Function as a Service).

Packages

Manage code packages and deployments. To learn more about Dataloop's packages, see the package.

# Delete packages
package.delete()

# Push packages
project.packages.push(src_path='/path_to_my_edited code', package_name=package.name)

# to see the package versions 
package.versions

# to see the latest package version
package.version

# Deploy package
package.deploy()

# Get package
package = dl.packages.get(package_id='my_package_Id')

# Get packages list
pack_list = dl.packages.list()

# Open package on the web
package.open_in_web()

Services

Manage services and bots. To learn more about Dataloop's services, see the service.

# Open service on the web
service.open_in_web()

# to pause the service
service.pause()

# to resume the service
service.resume()

# Create a bot
bot = project.bots.create('bot_name')

# Get services
service = dl.services.get(service_name="my_service_name")

# Get services list
dl.services.list().print()

# Delete service
service.delete()

Triggers

Automate actions in response to dataset or item events. To learn more about Dataloop's triggers, see the trigger.

# Delete triggers
trigger.delete()

# Trigger for Items Uploaded to Directory /Input
filters = dl.Filters(field='dir', values='/input')
trigger = service.triggers.create(function_name='run', resource=dl.TriggerResource.ITEM,
actions=dl.TriggerAction.CREATED,
name='items-created-trigger', filters=filters)

# Get triggers
service = dl.triggers.get(trigger_name="my_trigger_name")

# Get triggers lists
dl.triggers.list().print()

# Trigger for Items Uploaded to Directory /Input
filters = dl.Filters(field='dir', values='/input')
trigger = service.triggers.create(function_name='run', resource=dl.TriggerResource.ITEM,
actions=dl.TriggerAction.CREATED,
name='items-created-trigger', filters=filters)