Encord SDK

https://docs.encord.com/sdk-documentation
Admin
Encord SDK is a Python interface for programmatically interacting with the Encord platform to build...
Tokens:406,379
Snippets:2,034
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example Migration

Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-editor-logs

Full example showing the transition from old activity log iteration to new editor log iteration.

```python
logs = project.get_activity_logs()

for log in logs:
    if log["action"] == "LABEL_CREATED":
        print(log["user"], log["details"])
```

```python
logs = project.get_editor_logs(event_types=["LABEL_CREATED"])

for log in logs:
    print(log["actor"]["email"], log["payload"])
```

--------------------------------

### Install Python dependencies

Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-converting-ontology-shapes

Run this command to install the necessary libraries for the conversion script.

```bash
python -m pip install tqdm typer opencv-python numpy encord
```

--------------------------------

### Full Example: 2-panel split

Source: https://docs.encord.com/sdk-documentation/index-sdk/sdk-data-groups

A complete example demonstrating connection to Encord and creation of a simple 2-panel layout.

```python
from uuid import UUID

from encord.orm.storage import DataGroupCustom
from encord.user_client import EncordUserClient
from encord.orm.group_layout import (
    DataUnitTile,
    LayoutGrid,
    LayoutSettings,
    TileSettings,
)

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Folder ID
DATASET_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Dataset ID
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Project ID

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

layout = LayoutGrid(
    direction="row",
    first=DataUnitTile(key="instructions"),
    second=DataUnitTile(key="image"),
    split_percentage=30,  # 30% for "instructions", 70% for "image"
)


layout_contents = {
    "instructions": UUID("00000000-0000-0000-0000-000000000000"),  # File ID
    "image": UUID("11111111-1111-1111-1111-111111111111"),        # File ID
}
```

--------------------------------

### Full CVAT Import Workflow

Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-import-cvat

A complete example demonstrating authentication, starting the import, polling for the result, and handling potential issues.

```python
# Import dependencies
from encord import EncordUserClient
from encord.orm.project import ReviewMode
from encord.utilities.client_utilities import LocalImport

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key

# Path to the exported CVAT folder. It must contain:
#   <CVAT_EXPORT_DIR>/annotations.xml   <- the CVAT XML export
#   <CVAT_EXPORT_DIR>/images/           <- referenced image files
#
# Export using:
#   "CVAT for images 1.1"
#
# Ensure:
#   "Save images" is enabled.
CVAT_EXPORT_DIR = "/Users/chris-encord/cvat-exports/b1"

# Name of the Encord dataset/project to create.
DATASET_NAME = "b1"

# Create Encord client using SSH private key authentication.
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use:
    # domain="https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Step 1:
# Start the asynchronous CVAT import.
#
# This uploads the images and submits the CVAT annotations.xml file.
cvat_import_uuid = user_client.create_project_from_cvat_start(
    import_method=LocalImport(file_path=CVAT_EXPORT_DIR),
    dataset_name=DATASET_NAME,
    review_mode=ReviewMode.UNLABELLED,
    transform_bounding_boxes_to_polygons=False,
)

print(f"CVAT import started. import_uuid={cvat_import_uuid}")

# Step 2:
# Poll until the import process completes.
result = user_client.create_project_from_cvat_get_result(cvat_import_uuid)

# Step 3:
# Check whether the import succeeded.
if hasattr(result, "project_hash"):
    print(
        f"Import succeeded. "
        f"project_hash={result.project_hash}, "
        f"dataset_hash={result.dataset_hash}"
    )

    # Optional:
    # Display warnings, errors, or informational messages returned by the import.
    issues = getattr(result, "issues", None)

    if issues and (issues.errors or issues.warnings or issues.info):
        print(f"Import issues: {issues}")

else:
    print(f"Import failed. issues={getattr(result, 'issues', None)}")
```

--------------------------------

### Install Encord SDK

Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/installation-sdk

Use this command to install the Encord SDK package from PyPI.

```terminal
python3 -m pip install encord
```

--------------------------------

### Import Audio Regions

Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-audio-classifications

This example shows how to authenticate with the Encord SDK, retrieve a project, and add audio region annotations (defined by start and end frames) to specific audio files.

```APIDOC
## SDK Method: label_row.add_object_instance

### Description
Adds an object instance, such as an audio region, to a specific label row in an Encord project.

### Usage
1. Initialize the label row using `label_row.initialise_labels(bundle=bundle)`.
2. Create an `ObjectInstance` from an ontology object.
3. Define the `AudioCoordinates` with the desired frame ranges.
4. Use `label_row.add_object_instance(audio_object_instance)` to link the annotation.
5. Call `label_row.save()` to persist the changes to the server.

### Parameters
- **audio_object_instance** (ObjectInstance) - The instance created from the project ontology.
- **label_row** (LabelRow) - The target label row object representing the audio file.

### Example
```python
# Instantiate an object instance from the ontology node
audio_object_instance: ObjectInstance = audio_ontology_object.create_instance()

# Set object instance with specific start and end frames
audio_object_instance.set_for_frames(
    coordinates=AudioCoordinates(range=[Range(start=start, end=end)]),
    frames=0,
    manual_annotation=True,
    confidence=1.0,
)

# Link the object instance to the label row
label_row.add_object_instance(audio_object_instance)

# Upload the label to the server
label_row.save()
```
```

--------------------------------

### Create Image Sequences from Files

Source: https://docs.encord.com/sdk-documentation/index-sdk/sdk-image-groups-image-sequences

Use these examples to create image sequences from local file paths. The advanced example demonstrates how to include client metadata and process multiple sequences in a loop.

```python
from pathlib import Path
from uuid import UUID

from encord import EncordUserClient

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
FOLDER_ID = "00000000-0000-0000-0000-000000000000"

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

sequence_uuid: UUID = folder.create_image_sequence(
    file_paths=[
        Path("/path/to/frame001.jpg"),
        Path("/path/to/frame002.jpg"),
        Path("/path/to/frame003.jpg"),
    ],
    title="drive-sequence-001",
)

print(f"Created image sequence with UUID: {sequence_uuid}")
```

```python
from pathlib import Path
from uuid import UUID

from encord import EncordUserClient

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Folder ID

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

image_sequences = [
    {
        "title": "drive-sequence-001",
        "file_paths": [
            Path("/path/to/frame001.jpg"),
            Path("/path/to/frame002.jpg"),
            Path("/path/to/frame003.jpg"),
        ],
        "client_metadata": {
            "sequence_id": "001",
            "scenario": "urban",
        },
    },
    {
        "title": "drive-sequence-002",
        "file_paths": [
            Path("/path/to/frame004.jpg"),
            Path("/path/to/frame005.jpg"),
            Path("/path/to/frame006.jpg"),
        ],
        "client_metadata": {
            "sequence_id": "002",
            "scenario": "highway",
        },
    },
]

for image_sequence in image_sequences:
    sequence_uuid: UUID = folder.create_image_sequence(
        file_paths=image_sequence["file_paths"],
        title=image_sequence["title"],
        client_metadata=image_sequence["client_metadata"],
    )

    print(
        f"Created image sequence '{image_sequence['title']}' "
        f"with UUID: {sequence_uuid}"
    )
```

--------------------------------

### Example Output Global

Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-convert-manualqa-workflow

Console output for the global Encord environment.

```text
100%|██████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:07<00:00,  7.57s/it]
Done!
Access project on https://app.encord.com/projects/view/<target_project_hash>/summary
```

--------------------------------

### Merge Script Output Examples

Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-merge-projects

Console output examples for the merge script, showing progress bars and the final project access URL for Global and US environments.

```text
Merging in project <project_hash-1>
100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00,  1.02it/s]
Merging in project <project_hash-2>
100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 21/21 [00:13<00:00,  1.54it/s]
Done!
Access project on https://app.encord.com/projects/view/<target_project_hash>/summary
```

```text
Merging in project <project_hash-1>
100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00,  1.02it/s]
Merging in project <project_hash-2>
100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 21/21 [00:13<00:00,  1.54it/s]
Done!
Access project on https://app.us.encord.com/projects/view/<target_project_hash>/summary
```

--------------------------------

### Example output

Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/sdk-register-data-aws

Displays the expected console output when running the data registration script.

```text
add_private_data_to_dataset job started with upload_job_id=c4026edb-4fw2-40a0-8f05-a1af7f465727.
SDK process can be terminated, this will not affect successful job execution.
You can follow the progress in the web app via notifications.
add_private_data_to_dataset job completed with upload_job_id=c4026edb-4fw2-40a0-8f05-a1af7f465727.
```

--------------------------------

### Create Image Groups from Files

Source: https://docs.encord.com/sdk-documentation/index-sdk/sdk-image-groups-image-sequences

Use these examples to create image groups from local file paths. The advanced example demonstrates how to include client metadata and process multiple groups in a loop.

```python
from pathlib import Path
from uuid import UUID

from encord import EncordUserClient

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
FOLDER_ID = "00000000-0000-0000-0000-000000000000"

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

group_uuid: UUID = folder.create_image_group(
    file_paths=[
        Path("/path/to/front.jpg"),
        Path("/path/to/side.jpg"),
        Path("/path/to/rear.jpg"),
    ],
    title="vehicle-inspection-001",
)

print(f"Created image group with UUID: {group_uuid}")
```

```python
from pathlib import Path
from uuid import UUID

from encord import EncordUserClient

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
FOLDER_ID = "00000000-0000-0000-0000-000000000000"

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

image_groups = [
    {
        "title": "vehicle-inspection-001",
        "file_paths": [
            Path("./images/vehicle-001/front.jpg"),
            Path("./images/vehicle-001/side.jpg"),
            Path("./images/vehicle-001/rear.jpg"),
        ],
        "client_metadata": {
            "inspection_id": "001",
            "vehicle_type": "car",
        },
    },
    {
        "title": "vehicle-inspection-002",
        "file_paths": [
            Path("./images/vehicle-002/front.jpg"),
            Path("./images/vehicle-002/side.jpg"),
            Path("./images/vehicle-002/rear.jpg"),
        ],
        "client_metadata": {
            "inspection_id": "002",
            "vehicle_type": "truck",
        },
    },
]

for image_group in image_groups:
    group_uuid: UUID = folder.create_image_group(
        file_paths=image_group["file_paths"],
        title=image_group["title"],
        client_metadata=image_group["client_metadata"],
    )

    print(
        f"Created image group '{image_group['title']}' "
        f"with UUID: {group_uuid}"
    )
```

--------------------------------

### Retrieve and Print Workflow Stages

Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-workflows-stages

Use these examples to access the workflow stages of a project. The boilerplate provides a template, while the example shows concrete values for authentication and project identification.

```python
# Import dependencies
from encord import EncordUserClient, Project


SSH_PATH = "<file-path-to-private-key-file>"
PROJECT_HASH = "<unique-id-for-project>"

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

# Get project
project: Project = user_client.get_project(PROJECT_HASH)

# Print all Workflow stages
for idx, stage in enumerate(project.workflow.stages):
    print(f"Stage #{idx}: {stage}")
```

```python
# Import dependencies
from encord import EncordUserClient, Project


SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"
PROJECT_HASH = "2c2a74d0-d33d-43b2-b5dd-1c6c3e6d7b6d"

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

# Get project
project: Project = user_client.get_project(PROJECT_HASH)

# Print all Workflow stages
for idx, stage in enumerate(project.workflow.stages):
    print(f"Stage #{idx}: {stage}")
```

--------------------------------

### Example Output US

Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-convert-manualqa-workflow

Console output for the US Encord environment.

```text
100%|██████████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:07<00:00,  7.57s/it]
Done!
Access project on https://app.us.encord.com/projects/view/<target_project_hash>/summary
```

--------------------------------

### Initialize Encord Client and Project

Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-labels-import-3d

Setup the Encord user client and retrieve the project ontology to prepare for label imports.

```python
# Import dependencies
from pathlib import Path

from encord import EncordUserClient, Project
from encord.objects import (
    ChecklistAttribute,
    NumberAttribute,
    Object,
    ObjectInstance,
    Option,
    RadioAttribute,
    TextAttribute,
)
from encord.objects.attributes import NumericAttribute
from encord.objects.coordinates import PointCoordinate3D, PolylineCoordinates

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the unique ID for the Project
BUNDLE_SIZE = 100

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Get project for which labels are to be added
project: Project = user_client.get_project(PROJECT_ID)
assert project is not None, "Project not found — check PROJECT_ID"

# Get ontology structure
ontology_structure = project.ontology_structure
assert ontology_structure is not None, "Ontology structure is missing in the project"

# Get polyline object for Object of Interest
polyline_ontology_object: Object = ontology_structure.get_child_by_title(title="Object of Interest", type_=Object)
assert polyline_ontology_object is not None, "Polyline object 'Object of Interest' not found in ontology"
```

--------------------------------

### Project Setup and Migration Initialization

Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-convert-manualqa-workflow

Imports necessary libraries and defines functions to create the target project and initiate the bundle processing.

```python
# Import dependencies
  import argparse
  import time
  import logging
  from typing import List, Optional
  from encord import EncordUserClient, Project
  from tqdm import tqdm

  # Create target workflow Project
  def create_target_project(
      user_client: EncordUserClient,
      source_project_hash: str,
      target_project_name: str,
      workflow_template_hash: str,
  ) -> Project:
      # Retrieve all the required information you need to create your target project from the source Project
      source_p = user_client.get_project(source_project_hash)
      source_dataset_hashes = {x["dataset_hash"] for x in source_p.datasets}
      ontology_hash = source_p.ontology_hash

      target_project_hash: str = user_client.create_project(
          target_project_name,
          list(source_dataset_hashes),
          ontology_hash=ontology_hash,
          workflow_template_hash=workflow_template_hash,
      )

      return user_client.get_project(target_project_hash)


  # Migrate Projects using bundles to facilitate the migration of large Projects
  def process_by_bundle(
      source_project: Project,
      target_project: Project,
      bundle_size: int = 100,
      feature_hashes_to_include: Optional[List[str]] = None,
  ) -> List[str]:
      new_problematic_label_rows = []
      all_source_label_rows = source_project.list_label_rows_v2()
```

--------------------------------

### Install Python dependencies

Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-converting-ontology-shapes

Command to install the necessary packages for the conversion script.

```bash
python -m pip install tqdm typer encord
```

--------------------------------

### Initialize Project and Skeleton Objects

Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-import-labels-to-consensus-branches

Setup the Encord client, access a specific project branch, and retrieve ontology skeleton templates.

```python
# Import dependencies
from pathlib import Path
from encord import EncordUserClient, Project
from encord.objects import Object, ObjectInstance
from encord.objects.coordinates import SkeletonCoordinate, SkeletonCoordinates
from encord.objects.skeleton_template import SkeletonTemplate

# Configuration
SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"  # Path to your SSH private key
PROJECT_ID = "a4fe6c6a-2a13-4b3d-bd20-13d57421ecbb"  # Unique project id
CONSENSUS_BRANCH_NAME = "my-label-branch-I"  # Specify your label branch
DATA_UNIT_TITLE = "strawberries_10.jpg"  # Specific data unit title
ONTOLOGY_OBJECT_TITLE = "Strawberry"  # Name of the object in your ontology
SKELETON_TEMPLATE_NAME = "Triangle"  # Name of the skeleton template

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which labels are to be added
project: Project = user_client.get_project(PROJECT_ID)

# Specify the data unit to label in the given branch
label_row = project.list_label_rows_v2(
    branch_name=CONSENSUS_BRANCH_NAME,  # Filter by label branch
    data_title_eq=DATA_UNIT_TITLE
)[0]

# Initialize labels for the label row
label_row.initialise_labels()

# Find a skeleton annotation object in the project ontology
skeleton_ontology_object: Object = project.ontology_structure.get_child_by_title(
    title=ONTOLOGY_OBJECT_TITLE, type_=Object
)
skeleton_template: SkeletonTemplate = project.ontology_structure.skeleton_templates[SKELETON_TEMPLATE_NAME]

# OBJECT PRIMITIVE 1 - START
# Instantiate an object instance from the skeleton ontology node
skeleton_object_instance_01: ObjectInstance = skeleton_ontology_object.create_instance()
```

--------------------------------

### Initialize Encord Client and Prepare Bitmasks

Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual

Setup the Encord user client and prepare boolean numpy arrays for bitmask coordinates.

```python
# Import dependencies
import numpy as np

from pathlib import Path
from encord import EncordUserClient, Project
from encord.objects import (
    Object,
    ObjectInstance,
    RadioAttribute,
    ChecklistAttribute,
    TextAttribute,
    Option
)
from encord.objects.coordinates import BitmaskCoordinates
from encord.objects.attributes import NumericAttribute

# First, we need to prepare the mask itself.
# For simplicity, we'll mask the entire frame
# Note, that the size of the mask must be identical to the size of the image/frame
numpy_coordinates = np.ones((1080, 1920))

# we also need to make sure that the image/frame is in boolean format
numpy_coordinates = numpy_coordinates.astype(bool)

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
PROJECT_ID = "00000000-0000-0000-0000-000000000000"

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Get project for which labels are to be added
project: Project = user_client.get_project(PROJECT_ID)

# Create radio button attribute for apple type
ontology_structure = project.ontology_structure

# Find a bounding box annotation object in the project ontology
bitmask_ontology_object: Object = ontology_structure.get_child_by_title(
    title="Apples", type_=Object
)

# Find radio attribute in the ontology
apple_type_radio_attribute = ontology_structure.get_child_by_title(
    type_=RadioAttribute, title="Type?"
)

# Find number attribute in the ontology
apple_quality_number_attribute = ontology_structure.get_child_by_title(type_=NumericAttribute, title="Overall Quality")
assert apple_quality_number_attribute is not None, "Number attribute 'Overall Quality' not found in ontology."
```

--------------------------------

### Bounding Box Import Example 1

Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-import-labels-to-consensus-branches

Example imports for a single bounding box.

```python
# Import dependencies
import os
from pathlib import Path
from encord import EncordUserClient, Project
from encord.objects import LabelRowV2, Object, OntologyStructure, ObjectInstance
from encord.objects.coordinates import BoundingBoxCoordinates, RotatableBoundingBoxCoordinates, PolygonCoordinates, PolylineCoordinates, PointCoordinate, BitmaskCoordinates
```

--------------------------------

### Setup Encord Client and Project

Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual

Configures the Encord user client and retrieves the project structure required for label operations.

```python
# Import dependencies
from pathlib import Path

from encord import EncordUserClient, Project
from encord.objects import ChecklistAttribute, Object, ObjectInstance, Option, RadioAttribute, TextAttribute
from encord.objects.coordinates import PointCoordinate, PolygonCoordinates
from encord.objects.attributes import NumericAttribute

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
# SSH_PATH = get_ssh_key() # replace it with access key
PROJECT_ID = "00000000-0000-0000-0000-000000000000"
BUNDLE_SIZE = 100

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Get project for which labels are to be added
project: Project = user_client.get_project(PROJECT_ID)
assert project is not None, "Project not found — check PROJECT_ID"

# Get ontology structure
ontology_structure = project.ontology_structure
assert ontology_structure is not None, "Ontology structure is missing in the project"
```

--------------------------------

### Initialize Project for Attribute Export

Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-export

Shows the initial setup steps for loading a project and its label rows to prepare for attribute extraction.

```python
# Import dependencies
import json
from collections.abc import Iterable

from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.attributes import Attribute, ChecklistAttribute, RadioAttribute, TextAttribute

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
# SSH_PATH = get_ssh_key() # replace it with access key
PROJECT_ID = "00000000-0000-0000-0000-000000000000"
DATA_UNIT = "cherries-010.jpg"
OUTPUT_FILE_PATH = "/Users/chris-encord/all_attributes_output.json"
BUNDLE_SIZE = 100

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Load project and label rows
project = user_client.get_project(PROJECT_ID)
assert project is not None, f"Project with ID {PROJECT_ID} could not be loaded"

label_rows = project.list_label_rows_v2(data_title_eq=DATA_UNIT)
assert label_rows, f"No label rows found for data unit: {DATA_UNIT}"
```

--------------------------------

### Delete issues example

Source: https://docs.encord.com/sdk-documentation/sdk-references/issues.issue_client

Example showing how to delete a single issue or a batch of issues.

```python
# Delete a single issue:
task.issues.delete([issue])

# Or delete several at once:
obsolete = [i for i in task.issues.list() if i.comments[0].content.startswith("[obsolete]")]
task.issues.delete(obsolete)
```

--------------------------------

### Update feature mapping example

Source: https://docs.encord.com/sdk-documentation/sdk-references/ml_models_client

Example JSON structure for updating feature mappings during a model attachment update.

```json
{
    "model_feature_0": "new_ontology_feature_hash_1",
    "model_feature_1": "new_ontology_feature_hash_2"
}
```

--------------------------------

### Initialize 3D Keypoints project

Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-labels-import-3d

Sets up the Encord client and retrieves the project ontology for 3D keypoint labeling.

```python
# Import dependencies
from encord import EncordUserClient, Project
from encord.objects import Object
from encord.objects.coordinates import PointCoordinate3D

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the unique ID for the Project
BUNDLE_SIZE = 100

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Get project for which labels are to be added
project: Project = user_client.get_project(PROJECT_ID)

# Create radio button attribute for Person type
ontology_structure = project.ontology_structure

# Find a keypoint annotation object in the project ontology
keypoint_ontology_object: Object = ontology_structure.get_child_by_title(title="Point of Interest", type_=Object)
assert keypoint_ontology_object is not None, "Keypoint object 'Point of Interest' not found in ontology."
```

--------------------------------

### Feature mapping example

Source: https://docs.encord.com/sdk-documentation/sdk-references/ml_models_client

Example JSON structure for mapping model features to project ontology feature hashes.

```json
{
    "model_feature_0": "ontology_feature_hash_1",
    "model_feature_1": "ontology_feature_hash_2"
}
```

--------------------------------

### Create and manage a group

Source: https://docs.encord.com/sdk-documentation/general-sdk/sdk-user-groups

Demonstrates initializing the client, creating a group, fetching by hash, updating metadata, and deleting a group.

```python
# Import dependencies
from encord import EncordUserClient

# Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )

# --- Create a group ---
group = user_client.create_group("Radiology Reviewers", description="Clinical review team")
print(group.group_hash, group.name, group.created_at)

# --- Fetch a specific group by its hash ---
group = user_client.get_group("<group_hash>")

# --- Rename or re-describe a group ---
group.update_group(name="Radiology QA", description="Updated description")

# --- Delete a group (also revokes any access it granted to resources) ---
user_client.delete_group("<group_hash>")
```

--------------------------------

### Create a Project with Encord SDK

Source: https://docs.encord.com/sdk-documentation/getting-started-sdk/sdk-get-started-project

Authenticates the user client and initializes a new project using specified resource hashes.

```python
# Import dependencies
from encord.user_client import EncordUserClient

# Authenticate using the path to your private key. Replace <private_key_path> with the path to your key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )

# Create a project. Substitute the project title, dataset hashes, and template hash. 
project = user_client.create_project(
    project_title="<project_title>",
    dataset_hashes=["<dataset_hash_1>", "<dataset_hash_2>"],
    ontology_hash= "<ontology_hash>"
    workflow_template_hash="<template_hash>"
)

# Prints the Project hash
print (project.project_hash)
```

```text
a8b8d026-1c99-4cfc-910d-7f66be957f3d
```

--------------------------------

### Nested Classification Attribute Examples

Source: https://docs.encord.com/sdk-documentation/ontologies-sdk/ontologies-create

Examples of classification attribute nesting structures allowed within Encord ontologies.

```text
 - Classification
      - Radio button
        - Radio button
          - Radio button
            - Radio button
             - Radio button
               - Radio button
                 - Radio button or Checklist or Text box
```

```text
 - Classification
      - Radio button
        - Radio button
          - Checklist
```

```text
 - Classification
      - Radio button
        - Radio button
          - Radio button
            - Text box
```

--------------------------------

### Checklist Classification Template Setup

Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-import-labels-to-consensus-branches

Initial setup and dependency imports for applying a checklist classification to a label row.

```python
# Import dependencies
      from __future__ import annotations
      from pathlib import Path
      from encord import EncordUserClient, Project
      from encord.objects import Classification
      from encord.objects.options import Option

      # Configuration
      SSH_PATH = "/Users/chris-encord/sdk-ssh-private-key.txt"  # Path to your SSH private key
      PROJECT_ID = "7d4ead9c-4087-4832-a301-eb2545e7d43b"  # Unique project id
      CONSENSUS_BRANCH_NAME = "<your-label-branch-name>"  # Specify your label branch
      DATA_UNIT_TITLE = "Blueberries_video.mp4"  # Specific data unit title
      ONTOLOGY_OBJECT_TITLE = "Many types of fruit?"  # Name of the classification in your ontology
      APPLE_OPTION_TITLE = "Apple"  # Title of the apple option
      KIWI_OPTION_TITLE = "Kiwi"  # Title of the kiwi option
```

--------------------------------

### Initialize Keypoints for Images/Videos

Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual

Imports necessary Encord classes to begin working with keypoint annotations.

```python
from encord import EncordUserClient, Project
from encord.objects import Object, ObjectInstance
from encord.objects.coordinates import PointCoordinate
```

--------------------------------

### Task Output Example

Source: https://docs.encord.com/sdk-documentation/projects-sdk/sdk-workflows-stages

Example output showing task details including UUIDs, timestamps, and associated data hashes.

```python
Task: uuid=UUID('643dc436-3c90-478b-a7f6-45cd70d0fc19') created_at=datetime.datetime(2024, 6, 30, 22, 46, 57, 229922) updated_at=datetime.datetime(2024, 6, 30, 23, 15, 28, 115530) assignee=None data_hash=UUID('809344fd-8935-4dde-81eb-36efb4e6d558') data_title='apples_01.jpg'
Task: uuid=UUID('6aae1e0b-8297-4efa-9274-e1355633010d') created_at=datetime.datetime(2024, 6, 30, 23, 15, 27, 488760) updated_at=datetime.datetime(2024, 6, 30, 23, 15, 27, 565142) assignee=None data_hash=UUID('22f8dc9a-deff-49a2-a2d2-3863cf20d4f4') data_title='apples_03.jpg'
Task: uuid=UUID('e9623d55-b166-4a7e-bf8e-4e3b635263db') created_at=datetime.datetime(2024, 6, 30, 23, 15, 29, 32894) updated_at=datetime.datetime(2024, 6, 30, 23, 15, 29, 149193) assignee=None data_hash=UUID('4dc183ba-4233-4cb1-a940-cb6b2bc38f35') data_title='apples_04.jpg'
Task: uuid=UUID('4ff5801d-ad1a-4304-8270-55be654d681a') created_at=datetime.datetime(2024, 6, 30, 23, 15, 30, 422) updated_at=datetime.datetime(2024, 6, 30, 23, 15, 30, 86008) assignee=None data_hash=UUID('36b0afd3-6ff8-4201-bf65-35a37f6fe5b5') data_title='apples_02.jpg'
```

--------------------------------

### Create and Configure Object Instances

Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual

Demonstrates creating an object instance and setting its attributes based on specific data types like radio buttons and text fields.

```python
assert blueberry_type in {
    "Bluegold",
    "Duke",
    "Blueray",
    "Other blueberry type",
}, f"Unexpected blueberry type '{blueberry_type}' in data unit '{data_unit}'"

if label_ref not in object_instances_by_label_ref:
    polygon_object_instance: ObjectInstance = polygon_ontology_object.create_instance()
    assert polygon_object_instance is not None, f"Failed to create ObjectInstance for {label_ref}"

    object_instances_by_label_ref[label_ref] = polygon_object_instance
    checklist_attribute = None

    # Set blueberry quality attribute 
    polygon_object_instance.set_answer(attribute=blueberry_quality_number_attribute, answer=blueberry_quality)

    # Set blueberry type attribute
    if blueberry_type == "Bluegold":
        assert bluegold_option is not None, "Missing 'bluegold_option'"
        polygon_object_instance.set_answer(
            attribute=blueberry_type_radio_attribute, answer=bluegold_option
        )
        checklist_attribute = bluegold_checklist_attribute
    elif blueberry_type == "Duke":
        assert duke_option is not None, "Missing 'duke_option'"
        polygon_object_instance.set_answer(attribute=blueberry_type_radio_attribute, answer=duke_option)
        checklist_attribute = duke_checklist_attribute
    elif blueberry_type == "Blueray":
        assert blueray_option is not None, "Missing 'blueray_option'"
        polygon_object_instance.set_answer(
            attribute=blueberry_type_radio_attribute, answer=blueray_option
        )
        checklist_attribute = blueray_checklist_attribute
    elif blueberry_type == "Other blueberry type":
        assert other_blueberry_option is not None, "Missing 'other_blueberry_option'"
        polygon_object_instance.set_answer(
            attribute=blueberry_type_radio_attribute, answer=other_blueberry_option
        )
        text_answer = item.get("Specify blueberry type", "")
        assert isinstance(text_answer, str), "'Specify blueberry type' must be a string"
        polygon_object_instance.set_answer(
            attribute=other_blueberry_option_text_attribute,
            answer=text_answer,
        )

    # Set checklist attributes
    checklist_answers = []
    quality_key = f"{blueberry_type.lower()}_quality_options"
    quality_options = item.get(quality_key, "").split(", ")
```

--------------------------------

### Configure Instructions and 2x2 Grid Layout

Source: https://docs.encord.com/sdk-documentation/index-sdk/sdk-data-groups

Setup for a complex layout using ORM classes, featuring a top instruction bar and a 2x2 video grid.

```python
from uuid import UUID

from encord.constants.enums import DataType
from encord.objects.metadata import DataGroupMetadata
from encord.orm.storage import DataGroupCustom, StorageItemType
from encord.user_client import EncordUserClient
from encord.orm.group_layout import (
    DataUnitTile,
    LayoutGrid,
    LayoutSettings,
    TileSettings,
)

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Folder ID
DATASET_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Dataset ID
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Project ID
```

--------------------------------

### JSON Import Templates and Examples

Source: https://docs.encord.com/sdk-documentation/index-sdk/custom-metadata/sdk-import-custom-metadata

Provides the structure for importing image groups, including basic data imports and examples with custom metadata fields.

```json
{
  "image_groups": [
    {
      "title": "<title 1>",
      "createVideo": True,
      "objectUrl_0": "<object url>"
    },
    {
      "title": "<title 2>",
      "createVideo": True,
      "objectUrl_0": "<object url>",
      "objectUrl_1": "<object url>",
      "objectUrl_2": "<object url>",
      "clientMetadata": {
        "optional": "metadata"
        "geo-point": {"latitude": +/- 90, "longitude": +/- 180}
        }
    }
  ],
  "skip_duplicate_urls": true
}
```

```json
{
  "image_groups": [
    {
      "title": "Image sequence 001",
      "createVideo": True,
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/01.jpg",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/02.jpg",
      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/DALL%C2%B7E+2022-09-08+18.53.25+-+firefighter+extinguishing+flames+around+computer+in+software+office+overgrown+by+foliage.png"
    },
    {
      "title": "Image sequence 002",
      "createVideo": True,
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-01.jpg",
      "objectUrl_1": "<https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-02.jpg",
      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/thing-03.jpg"
    }
  ],
  "skip_duplicate_urls": true
}
```

```json
{
  "image_groups": [
    {
      "title": "Blueberries sequence 01",
      "createVideo": True,
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-highbush-01.jpg",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-highbush-02.jpg",
      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/blueberry-highbush-03.jpg",
      "clientMetadata": {"Dark": True, "Location": "WA", "Date": "2024-02-02", "ACME Co ID": "73358daa-4f26-49bf-b03e-7d6d0a3c8bd7", "Priority": "3"}
    },
    {
      "title": "Cherries sequence 01",
      "createVideo": false,
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-bing-01.jpg",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-bing-02.jpg",
      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/cherry-bing-03.jpg",
      "clientMetadata": {"Dark": True, "Location": "WA", "Date": "2024-02-03", "ACME Co ID": "b73f3761-01ec-48b7-8d0c-b5f12a75e3d3", "Priority": "2"}
    }
  ],
  "skip_duplicate_urls": true
}
```

--------------------------------

### Initialize Encord Client

Source: https://docs.encord.com/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual

Setup code for importing necessary modules and authenticating with the Encord platform.

```python
# Import dependencies
from pathlib import Path

from encord import EncordUserClient, Project
from encord.objects import ChecklistAttribute, Object, ObjectInstance, Option, RadioAttribute, TextAttribute
from encord.objects.coordinates import PointCoordinate
from encord.objects.attributes import NumericAttribute

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"
# SSH_PATH = get_ssh_key() # replace it with access key
PROJECT_ID = "00000000-0000-0000-0000-000000000000"
BUNDLE_SIZE = 100

# Create user client using access key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)
```

--------------------------------

### Copy a Project with Basic Configuration

Source: https://docs.encord.com/sdk-documentation/projects-sdk/projects-and-workflows/sdk-copy-project

Demonstrates standard project duplication for both global and US-based Encord environments.

```python
# Import dependencies
from encord import EncordUserClient, Project

#Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>")

# Specify the project you'd like to copy using its Project hash
project = user_client.get_project("<project_hash>")

# Copy the project with attached datasets and collaborators
new_project_hash = project.copy_project(
    copy_datasets=True,
    copy_collaborators=True,
    copy_models=False,  # Not strictly needed
)
# Print the new project's hash
print(new_project_hash)
```

```python
# Import dependencies
from encord import EncordUserClient, Project

#Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>", domain="https://api.us.encord.com")

# Specify the Project you'd like to copy using its Project hash
project = user_client.get_project("<project_hash>")

# Copy the Project with attached Datasets and collaborators
new_project_hash = project.copy_project(
    copy_datasets=True,
    copy_collaborators=True,
    copy_models=False,  # Not strictly needed
)
# Print the new Project's hash
print(new_project_hash)
```
Tokens:
Raw