Active Collections

Filter Presets

Filter presets are saved groups of filter criteria that you can reuse across Active.

Create Filter Preset

Create a Filter Preset based on raw JSON.

For more information on creating your own filter presets using the SDK, contact us at [e-mail]

Template

# Import dependencies
from encord import EncordUserClient

from encord.orm.filter_preset import FilterPresetDefinition, FilterDefinition
from encord.orm.filter_preset import FilterPreset as OrmFilterPreset

SSH_PATH = "<file-path-to-ssh-key>"
PROJECT_ID = "<project-unique-id>"

# Initialize the user client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get project
project = user_client.get_project(PROJECT_ID)


# Define the filter preset structure

# Create a preset with the defined filter preset
preset = project.create_filter_preset(
    name="<name-for-your-preset>",
    filter_preset= FilterPresetDefinition(global_filters=FilterDefinition(
        filters= [{'key':'<key-name>',
        'include':True or False,
        'values' : [<fitler-values>],
        'type': '<client-metadata-type'}]
    )
 ))

# Output the result
print(f"Preset created with UUID: {preset.uuid}")
print("Preset contents: ", preset.get_filter_preset_json())

Update Filter Presets

All arguments are optional when updating a filter preset.

Template

# Import dependencies
from encord import EncordUserClient

from encord.orm.filter_preset import FilterPresetDefinition, FilterDefinition
from encord.orm.filter_preset import FilterPreset as OrmFilterPreset

SSH_PATH = "<file-path-to-ssh-key>"
PROJECT_ID = "<project-unique-id>"
PRESET_ID = "<preset-unique-id>"

# Initialize the user client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get project
project = user_client.get_project(PROJECT_ID)

# Create a preset with the defined filter preset
preset = project.get_filter_preset(filter_preset_uuid=PRESET_ID)
preset.update_preset(
    name="<updated-preset-name>",
    filter_preset= FilterPresetDefinition(global_filters=FilterDefinition(
        filters= [{'key':'<key-name>',
        'include':True or False,
        'values' : [<fitler-values>],
        'type': '<client-metadata-type>'}]
    )
  )
 )

# Output the result
print(f"Updated Preset with UUID: {preset.uuid}")

List Filter Presets

List all Filter Presets in Active by name with their unique identifier.

Template

# Import dependencies
from encord import EncordUserClient

SSH_PATH = "file-path-to-ssh-private-key"
PROJECT_ID = "<project_hash>"

user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get project
project = user_client.get_project(PROJECT_ID)

# Get Preset Filters for the project
presets = project.list_filter_presets()

# List Preset Filters by name and UUID
for preset in presets:
    print(preset.name, preset.uuid)

Delete Presets

Use the following code template to delete a preset filter in Active.

Template

# Import dependencies
from encord import EncordUserClient

SSH_PATH = "file-path-to-ssh-private-key"
PROJECT_ID = "<project-unique-id>"

# Preset ID to delete
PRESET_ID = "unique-preset-filter-id"  

user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get project
project = user_client.get_project(PROJECT_ID)

# Delete Preset Filter
project.delete_filter_preset(PRESET_ID)

View Preset JSON

This code outputs the filters that make up the Active filter preset in a JSON file format.

Template

# Import dependencies
from encord import EncordUserClient

from encord.orm.filter_preset import FilterPreset as OrmFilterPreset

SSH_PATH = "<file-path-to-ssh-private-key>"
PROJECT_ID = "<project-unique-id>"
PRESET_ID = "<uuid-of-the-preset-filter>"

user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Get project
project = user_client.get_project(PROJECT_ID)

# Get filter preset and return the JSON representation
filter_preset_json = project.get_filter_preset(filter_preset_uuid=PRESET_ID).get_filter_preset_json()

# Output the result
print("\nFormatted Output:\n")
print(filter_preset_json)

---

Collections

Active supports two types of Collections: Frame Collections and Label Collections.

Frame Collections are groups of frames (images and video frames) you selected by filtering, sorting, inspecting, and analyzing the data units in Active.

Label Collections are groups of labels, on your frames (images and video frames), that you selected by filtering, sorting, inspecting, and analyzing the labels on your data units in Active.

List Collections

List all Collections in an Active Project by name with their unique identifier.

Template List ALL Collections

from encord import EncordUserClient
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.orm.collection import ProjectCollectionType, ProjectDataCollectionItemRequest, ProjectLabelCollectionItemRequest, ProjectCollectionBulkItemResponse

SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<unique-annotate-project-id>"

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

project = user_client.get_project(PROJECT_ID)

print(project.title)

collections = project.list_collections()
for collection in collections:
    print(collection.name, collection.collection_type, collection.uuid)

List FRAME Collections

List all FRAME Collections in an Active Project by name with their unique identifier.

Template List FRAME Collections

from encord import EncordUserClient
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.orm.collection import ProjectCollectionType, ProjectDataCollectionItemRequest, ProjectLabelCollectionItemRequest, ProjectCollectionBulkItemResponse

SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<unique-annotate-project-id>"

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

project = user_client.get_project(PROJECT_ID)

print(project.title)

collections = project.list_collections()

for collection in collections:
    # Check if the collection type is 'FRAME'
    if collection.collection_type == ProjectCollectionType.FRAME:
        print(collection.name, collection.collection_type, collection.uuid)

List LABEL Collections

List all LABEL Collections in an Active Project by name with their unique identifier.

Template List LABEL Collections

from encord import EncordUserClient
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.orm.collection import ProjectCollectionType, ProjectDataCollectionItemRequest, ProjectLabelCollectionItemRequest, ProjectCollectionBulkItemResponse

SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<unique-annotate-project-id>"

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

pproject = user_client.get_project(PROJECT_ID)

print(project.title)

collections = project.list_collections()

# Specify LABEL Collections
if collection.collection_type == ProjectCollectionType.LABEL:
        print(collection.name, collection.collection_type, collection.uuid)

Create Collection

Create a Collection with a meaningful name and description in a Folder.

Template

from encord import EncordUserClient
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.orm.collection import ProjectCollectionType, ProjectDataCollectionItemRequest, ProjectLabelCollectionItemRequest

SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<unique-annotate-project-id>"

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

project = user_client.get_project(PROJECT_ID)

collection = project.create_collection(name="Test Collection 1", description="A useful and meaningful description for the Collection.", collection_type= "<FRAME-or-LABEL>")

print(collection)

Add Items to a Collection

You need the data hash of the data units in your Annotate Project to add the data units to an Active Collection.

Get Data ID

Get Data ID

Use the following code to get the Data ID (unique ID for data units from Dataset) from your Annotate Project:

Template Get Data ID

# Import dependencies
from encord import EncordUserClient

SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<project-unique-id>"

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)


# Specify Project. Replace <project_hash> with the hash of your Project.
project = user_client.get_project(PROJECT_ID)

# Get label rows for your Project
label_rows = project.list_label_rows_v2()

# Iterate through label rows and print data hashes and titles
for label_row in label_rows:
    print(f"Data hash: {label_row.data_hash}")
    print(f"Data title: {label_row.data_title}")
    print("---")  # Separator for readability

Get Annotation ID

Get Annotation ID

You need the Data ID, frame number, AND the Annotation ID (Object Hash) for the label or classification you want to add to the LABEL Collection.

The following code gets the Annotation ID for all the labels in an Annotate Project

Template Get Annotation ID

# Import dependencies
from encord import EncordUserClient

SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<project-unique-id>"

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)


# Specify Project. Replace <project_hash> with the hash of your Project.
project = user_client.get_project(PROJECT_ID)

# Get label rows for your Project
label_rows = project.list_label_rows_v2()

# Iterate through label rows and print data hashes, titles, and label hashes
for label_row in label_rows:
    print(f"Data hash: {label_row.data_hash}")
    print(f"Data title: {label_row.data_title}")
    print(f"Label hash: {label_row.data_hash}")
    print("---")  # Separator for readability

Add Items to FRAMES Collection

Add Items to FRAMES Collection

You need the Data ID and frame number of the frames you want to add to a Collection.

Template FRAMES

# Import dependencies
from encord import EncordUserClient
from encord.collection import ProjectCollection
from encord.orm.filter_preset import FilterPreset
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.orm.collection import ProjectCollectionType, ProjectDataCollectionItemRequest, ProjectLabelCollectionItemRequest


# Define constants
SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<project-unique-id>"

COLLECTION_ID = "<collection-unique-id>"

# Initialize the user client using the SSH private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific Project by ID
project = user_client.get_project(PROJECT_ID)


# Fetch the specific collection by hash
collection = project.get_collection(COLLECTION_ID)

# Add items to the collection and capture the response
response = collection.add_items([ProjectDataCollectionItemRequest(data_uuid="<data-unique-id>", frame=<frame-number>)])

# Print the success message
print(f"Added items to collection {COLLECTION_ID}.")

# Check if there were any failed items
if isinstance(response, ProjectCollectionBulkItemResponse):
    failed_items = response.failed_items
    if failed_items:
        print("The following items failed to be added to the collection:")
        for failed_item in failed_items:
            # Assuming failed_item is an instance of either ProjectDataCollectionItemRequest or ProjectLabelCollectionItemRequest
            print(f"Failed item: {failed_item}")
    else:
        print("All items were added successfully.")
else:
    print("Unexpected response format.")

Add items to LABEL Collection

Add Items to LABEL Collection

You need the Data ID, frame number, AND the Annotation ID to add items to a LABEL Collection.

Template LABEL

# Import dependencies
from encord import EncordUserClient
from encord.collection import ProjectCollection
from encord.orm.filter_preset import FilterPreset
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.orm.collection import ProjectCollectionType, ProjectDataCollectionItemRequest, ProjectLabelCollectionItemRequest


# Define constants
SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<project-unique-id>"

COLLECTION_ID = "<collection-unique-id>"

# Initialize the user client using the SSH private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)


# Fetch the specified Project by ID
project = user_client.get_project(PROJECT_ID)


# Fetch the specific Collection by ID
collection = project.get_collection(COLLECTION_ID)


# Add items to the collection and capture the response
response = collection.add_items([ProjectLabelCollectionItemRequest(data_uuid="<data-unique-id>", frame=<frame-number>, annotation_id="<annotation-unique-id>")])

# Print the success message
print(f"Added items to collection {COLLECTION_ID}.")

# Check if there were any failed items
if isinstance(response, ProjectCollectionBulkItemResponse):
    failed_items = response.failed_items
    if failed_items:
        print("The following items failed to be added to the collection:")
        for failed_item in failed_items:
            # Assuming failed_item is an instance of ProjectLabelCollectionItemRequest
            print(f"Failed item: {failed_item}")
    else:
        print("All items were added successfully.")
else:
    print("Unexpected response format.")

Add Items to a Collection using Presets

The code to add items to a Frame Collection or a Label Collection is the same.

You can find the Preset ID for your preset in the Active UI.

Template

# Import dependencies
from encord import EncordUserClient
from encord.collection import ProjectCollection
from encord.orm.filter_preset import FilterPreset
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.orm.collection import ProjectCollectionType, ProjectDataCollectionItemRequest, ProjectLabelCollectionItemRequest


# Define constants
SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<project-unique-id>"

COLLECTION_ID = "<collection-unique-id>"

PRESET_ID = "<preset-unique-id>"

# Initialize the user client using the SSH private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific Project by ID
project = user_client.get_project(PROJECT_ID)


# Fetch the specific Collection by ID
collection = project.get_collection(COLLECTION_ID)


collection.add_preset_items(PRESET_ID)

print(f"Added items to collection {COLLECTION_ID}.")

Remove Items from a Collection

Remove items from a Frame or Label Collection.

Get Data ID

Get Data ID

Use the following code to get the Data ID (unique ID for data units from Dataset) from your Annotate Project:

Template Get Data ID

# Import dependencies
from encord import EncordUserClient

SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<project-unique-id>"

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)


# Specify Project. Replace <project_hash> with the hash of your Project.
project = user_client.get_project(PROJECT_ID)

# Get label rows for your Project
label_rows = project.list_label_rows_v2()

# Iterate through label rows and print data hashes and titles
for label_row in label_rows:
    print(f"Data hash: {label_row.data_hash}")
    print(f"Data title: {label_row.data_title}")
    print("---")  # Separator for readability

Get Annotation ID

Get Annotation ID

You need the Data ID AND the Annotation ID (Object Hash) for the label or classification you want to remove from the LABEL Collection.

The following code gets the Annotation ID for all the labels in an Annotate Project

Template Get Annotation ID

# Import dependencies
from encord import EncordUserClient

SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<project-unique-id>"

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)


# Specify Project. Replace <project_hash> with the hash of your Project.
project = user_client.get_project(PROJECT_ID)

# Get label rows for your Project
label_rows = project.list_label_rows_v2()

# Iterate through label rows and print data hashes and titles
for label_row in label_rows:
    print(f"Data hash: {label_row.data_hash}")
    print(f"Data title: {label_row.data_title}")
    print("---")  # Separator for readability

Remove Items from FRAME Collections

Remove Items from FRAME Collections

You need the Data ID of frames to remove items from a FRAME Collection.

Template FRAMES

# Import dependencies
from encord import EncordUserClient
from encord.collection import ProjectCollection
from encord.orm.filter_preset import FilterPreset
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.orm.collection import ProjectCollectionType, ProjectDataCollectionItemRequest, ProjectLabelCollectionItemRequest


# Define constants
SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<project-unique-id>"

COLLECTION_ID = "<collection-unique-id>"

# Initialize the user client using the SSH private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific Project by ID
project = user_client.get_project(PROJECT_ID)


# Fetch the specific Collection by ID
collection = project.get_collection(COLLECTION_ID)


# Add images or video frames to a FRAMES Collection
collection.remove_items([ProjectDataCollectionItemRequest(data_uuid="<data-unique-id>", frame=0)])

print(f"Removed items to collection {COLLECTION_ID}.")

Remove Items from LABEL Collections

Remove Items from LABEL Collections

You need the Data ID and Annotation ID to remove items from LABEL Collections.

Template LABEL

# Import dependencies
from encord import EncordUserClient
from encord.collection import ProjectCollection
from encord.orm.filter_preset import FilterPreset
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.orm.collection import ProjectCollectionType, ProjectDataCollectionItemRequest, ProjectLabelCollectionItemRequest


# Define constants
SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<project-unique-id>"

COLLECTION_ID = "<collection-unique-id>"

# Initialize the user client using the SSH private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)


# Fetch the specified Project by ID
project = user_client.get_project(PROJECT_ID)


# Fetch the specific Collection by ID
collection = project.get_collection(COLLECTION_ID)


collection.remove_items([ProjectLabelCollectionItemRequest(data_uuid="data-unique-id", frame=<frame-number>, annotation_id="<annotation-unique-id>")])

print(f"Removed items to collection {COLLECTION_ID}.")

Remove Items From a Collection using Presets

The code to remove items from a Frame Collection or a Label Collection is the same.

You can find the Preset ID for your preset in the Active UI.

Template

# Import dependencies
from encord import EncordUserClient
from encord.collection import ProjectCollection
from encord.orm.filter_preset import FilterPreset
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.orm.collection import ProjectCollectionType, ProjectDataCollectionItemRequest, ProjectLabelCollectionItemRequest


# Define constants
SSH_PATH = "<file-path-to-ssh-private-key>"

PROJECT_ID = "<project-unique-id>"

COLLECTION_ID = "<collection-unique-id>"

PRESET_ID = "<preset-unique-id>"

# Initialize the user client using the SSH private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specific Project by ID
project = user_client.get_project(PROJECT_ID)


# Fetch the specific Collection by ID
collection = project.get_collection(COLLECTION_ID)


collection.remove_preset_items(PRESET_ID)

print(f"Removed items from Collection {COLLECTION_ID}.")

List all Items in a Collection

List All Frames in a Collection

List all Frames in a Collection

Lists all FRAMES in a Collection.

Template

# Import dependencies
from encord import EncordUserClient
from encord.collection import ProjectCollection
from encord.orm.filter_preset import FilterPreset
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.orm.collection import ProjectCollectionType, ProjectDataCollectionItemRequest, ProjectLabelCollectionItemRequest

# Define constants
SSH_PATH = "<file-path-to-private-ssh-key>"
PROJECT_ID = "<project-unique-id>"
COLLECTION_ID = "<collection-unique-id>"

# Initialize the user client using the SSH private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specified Project by ID
project = user_client.get_project(PROJECT_ID)

# Fetch the specific Collection by ID
collection = project.get_collection(COLLECTION_ID)

frame_list = []

# Iterate over frames
for label_row, frames in collection.list_frames():
    frame_list.extend(frames)
    for frame in frames:
        print(f"UUID: {label_row.data_hash}, Frame number: {frame.frame}")  

List All Labels in a Collection

List All Labels in a Collection

Lists all annotations (object labels and classifications) in a Label Collection with the frame ID and frame number.

Template List Annotations in Collection

# Import dependencies
from encord import EncordUserClient
from encord.collection import ProjectCollection
from encord.orm.filter_preset import FilterPreset
from encord.objects.coordinates import BoundingBoxCoordinates
from encord.orm.collection import ProjectCollectionType, ProjectDataCollectionItemRequest, ProjectLabelCollectionItemRequest

# Define constants
SSH_PATH = "<file-path-to-private-key>"
PROJECT_ID = "<project-unique-id>"
COLLECTION_ID = "<collection-unique-id>"

# Initialize the user client using the SSH private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Fetch the specified Project by ID
project = user_client.get_project(PROJECT_ID)

# Fetch the specific Collection by ID
collection = project.get_collection(COLLECTION_ID)

annotation_list = []

# Iterate over annotations
for label_row, annotations in collection.list_annotations():
    annotation_list.extend(annotations)
    for annotation in annotations:
        print(f"UUID: {label_row.data_hash}, Frame number: {annotation.frame}, Annotation: {annotation.annotation_id}")