Active API & SDK
Active Collections
Get Started
- Global and US Encord Platforms
- 1. Prerequisites and Installation
- 2. Register Cloud Data
- 3. Set Up Your Project and Team
- Export Labels
General
Index
Projects
Labels
Datasets
Active API & SDK
Active Collections
Learn the basics of using the SDK with Active Data and Label Collections and Filter Presets.
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 support@encord.com
# 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.
# 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.
# 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.
# 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.
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.
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.
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.
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
Use the following code to get the Data ID (unique ID for data units from Dataset) from your Annotate Project:
# 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
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
# 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
You need the Data ID and frame number of the frames you want to add to a 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-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
You need the Data ID, frame number, AND the Annotation ID to add items to a LABEL 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-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.
# 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
Use the following code to get the Data ID (unique ID for data units from Dataset) from your Annotate Project:
# 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
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
# 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
You need the Data ID of frames to remove items from a FRAME 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-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
You need the Data ID and Annotation ID to remove items from LABEL Collections.
# 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.
# 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
Lists all FRAMES in a 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-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
Lists all annotations (object labels and classifications) in a Label Collection with the frame ID and frame number.
# 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}")
Was this page helpful?
On this page
- Filter Presets
- Create Filter Preset
- Update Filter Presets
- List Filter Presets
- Delete Presets
- View Preset JSON
- Collections
- List Collections
- List FRAME Collections
- List LABEL Collections
- Create Collection
- Add Items to a Collection
- Add Items to a Collection using Presets
- Remove Items from a Collection
- Remove Items From a Collection using Presets
- List all Items in a Collection