SDK Quick Peek

Register/Import Data

• Register cloud data: storage_folder.add_private_data_to_folder_start(integration_id=integration, private_files="path/to/json/file.json", ignore_errors=True)
• List items in storage folder: storage_folder.list_items()

Folders

• Create Folder:

folder_name = "<folder_name>"
folder_description = "A folder to store my files"
folder_metadata = {"my": "folder_metadata"}
storage_folder = user_client.create_storage_folder(folder_name, folder_description,client_metadata=folder_metadata)

• Create Cloud-sync Folder:

storage_folder = user_client.create_storage_folder(
    name=folder_name,
    description=folder_description,
    client_metadata=folder_metadata,
    cloud_synced_folder_params=(integration_uuid=UUID(INTEGRATION_UUID), remote_url=REMOTE_URL,)
)

• Move Files from one folder to another: item.move_to_folder(TARGET_FOLDER.uuid)

Ontology

• Create Ontology: cat_ontology = user_client.create_ontology(title="My test Ontology", structure=ontology_structure)
• View Ontology structure: user_client.get_ontology("unique-id-of-your-ontology")

Datasets

• Create Dataset: user_client.create_dataset(dataset_title="Houses", dataset_type=StorageLocation.AWS, create_backing_folder=False,)
• Delete data from Dataset:

dataset.delete_data(
    [
        "<video1_data_hash\>",
        "<image_group1_data_hash>",
    ]
)

Projects

• Create Project: project = user_client.create_project(project_title="<project_title>", dataset_hashes=["<dataset_hash_1>", "<dataset_hash_2>"], workflow_template_hash="<template_hash>")
• Copy Project:

new_project_hash = project.copy_project(
    copy_datasets=True,
    copy_collaborators=True,
    copy_models=False,  # Not strictly needed
)

• Set Project status: project.set_status(ProjectStatus.COMPLETE)
• Get Tasks from Stage:

stage = project.workflow.get_stage(name="Annotate 1", type_=AnnotationStage)
for task in stage.get_tasks()

• Move tasks in non-Consensus Projects:

for task in stage.get_tasks():
    # The task is submitted as the user who is currently assigned to the task
    task.submit(retain_assignee=True, bundle=bundle)

• Reject tasks:

for task in stage.get_tasks(data_hash=data_hashes):
    task.assign("[e-mail]")
    task.reject(bundle=bundle)

• Approve tasks:

for task in stage.get_tasks(data_hash=data_hashes):
    task.assign("[e-mail]")
    task.approve(bundle=bundle)

• Add Taskers to Project:

added_users = project.add_users(
    ["[e-mail]", "[e-mail]"],
    ProjectUserRole.ANNOTATOR,
)

• Add issues to tasks:

REVIEW_ISSUES = [
    {
        "data_title": "cherries-sequence",
        "file_issue": {"text": "Review file issue 1", "tags": ["incorrect object"]},
        "frame_issue": {"frame": 3, "text": "Review frame issue 1", "tags": ["label too large"]},
        "coordinate_issue": {"frame": 0, "x": 0.3, "y": 0.3, "text": "Review coordinate issue 1", "tags": ["incorrect object", "label too large"]},
    }
]

task.issues.add_file_issue(issue["file_issue"]["text"], issue["file_issue"]["tags"])
if "frame_issue" in issue:
    fi = issue["frame_issue"]
    task.issues.add_frame_issue(fi["frame"], fi["text"], fi["tags"])
    ci = issue["coordinate_issue"]
    task.issues.add_coordinate_issue(ci["frame"], ci["x"], ci["y"], ci["text"], ci["tags"])

• Get timers in Project:

# Get Time Entries
start_date = datetime(2025, 1, 1)
end_date = datetime(2025, 6, 8)

# Returns all data
time_entries = list(project.list_time_spent(start=start_date, end=end_date))

• Automated labeling

# Fetch label row
sample_label = project.get_label_row("sample_label_uid")

# Prepare interpolation
key_frames = sample_label["data_units"]["sample_data_hash"]["labels"]
objects_to_interpolate = ["sample_object_uid"]

# Run interpolation
interpolation_result = project.object_interpolation(key_frames, objects_to_interpolate)

Labels

• Import labels (bounding box):

box_object_instance.set_for_frames(
    coordinates=BoundingBoxCoordinates(
        height=<numerical-value>,
        width=<numerical-value>,
        top_left_x=<numerical-value>,
        top_left_y=<numerical-value>,
    ),
    # Add the bounding box to the frames specified
    frames=<frame-number>,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
 )

• Import labels (rotatable bounding box):

 rbb_object_instance.set_for_frames(
    coordinates=RotatableBoundingBoxCoordinates(
    height=<height-value>
    width=<width-value>,
    top_left_x=<top-left-x-value>,
    top_left_y=<top-left-y-value>,
    theta=<angle-of-rotation>
    ),
    # Add the rotatable bounding box to frame number specified
    frames=<frame-number>,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

• Import labels (polygons)

polygon_object_instance.set_for_frames(
    coordinates=PolygonCoordinates(polygons=polygons),
    frames=0,
    manual_annotation=True,
    confidence=1.0,
    )

• Import labels (Polyline)

polyline_object_instance.set_for_frames(
    coordinates=PolylineCoordinates(
        [PointCoordinate(.x1,.y1), PointCoordinate(.x2,.y2), PointCoordinate(.x3,.y3), PointCoordinate(.13,.456)]
    ),
    # Add the polyline to the specified frame number
    frames=<frame-number>,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

• Import labels (keypoint)

keypoint_object_instance.set_for_frames(
    coordinates=PointCoordinate(
        x=<value-for-x-axis>
        y=<value-for-y-axis>
    ),
    # Add the keypoint to the specified frame number
    frames=<frame-number>,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

• Import labels (bitmask)

bitmask_object_instance.set_for_frames(
    # Create coordinates from provided numpy bitmask
    coordinates=BitmaskCoordinates(numpy_coordinates),
    # Add the bitmask to the first frame
    frames=0,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

• Import labels (skeleton)

skeleton_object_instance.set_for_frames(
    coordinates=skeleton_coordinates,
    # Add the polygon to the image
    frames=0,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

• Import classifications (Radio buttons options)

radio_classification_instance.set_for_frames(
    # Add the classification to the image
    frames=0,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

label_row.add_classification_instance(radio_classification_instance)

• Import classifications (checklist)

checklist_classification_instance = (
    checklist_ontology_classification.create_instance()
)

checklist_classification_instance.set_answer(
    [apple_option, kiwi_option]
)
checklist_classification_instance.set_for_frames(
    # Add the classification to the image
    frames=177,
    # There are multiple additional fields that can be set optionally:
    manual_annotation=True,
    confidence=1.0,
)

label_row.add_classification_instance(checklist_classification_instance)

Custom Metadata

• Create/Update custom metadata: curr_metadata.update(metadata_update)
• Copy custom metadata: curr_metadata = item.client_metadata.copy()

Data Groups

• Create Data Group:

for g in groups:
    group = folder.create_data_group(
        DataGroupGrid(
            name=g["name"],
            layout_contents=g["uuids"],
        )
    )

Collections

• Create Index pre-filter

preset = user_client.create_preset(
    name="name-of-my-preset",
    description="A useful and meaningful description for the preset.",
    filter_preset_json={
        "global_filters": {
            "filters": [
                {
                    ... define your filter here ...
                }
            ]
        }
    },
)

• Update Index Pre-filter:

preset.update_preset(
    name="updated-name-of-my-preset",
    description="Updated useful and meaningful description for the preset.",
    filter_preset_json={ ... }
)

• Delete Index Pre-filter: user_client.delete_preset(PRESET_ID)

• Add Index Pre-Filter data units to Index Collections: collection.add_preset_items(PRESET_ID)

• Remove Index Pre-Filter data units from Index Collections: collection.remove_preset_items(PRESET_ID)

• Create Index Collection: collection = user_client.create_collection(top_level_folder_uuid="root-folder-uuid", name="name-of-my-collection", description="A useful and meaningful description for the Collection.")